docker-compose/README.md

<div align="center">

```
    ___       ___       ___       ___       ___       ___
   /\  \     /\  \     /\__\     /\  \     /\  \     /\__\
  /::\  \   /::\  \   /:/  /    /::\  \   /::\  \   /:| _|_
 /::\:\__\ /::\:\__\ /:/__/    /:/\:\__\ /:/\:\__\ /::|/\__\
 \/\::/  / \/\::/  / \:\  \    \:\ \/__/ \:\/:/  / \/|::/  /
   /:/  /    /:/  /   \:\__\    \:\__\    \::/  /    |:/  /
   \/__/     \/__/     \/__/     \/__/     \/__/     \/__/
```

# ⚡ THE FALCON ⚡

**Captain Valknar's Legendary Starship**

[![Status](https://img.shields.io/badge/STATUS-DEEP_SPACE-00d4ff?style=for-the-badge&logo=spacex&logoColor=white)](https://pivoine.art)
[![Mission](https://img.shields.io/badge/MISSION-ALIEN_ENCOUNTERS-4169e1?style=for-the-badge&logo=rocket&logoColor=white)](https://sexy.pivoine.art)
[![Crew](https://img.shields.io/badge/CAPTAIN-VALKNAR-silver?style=for-the-badge&logo=linux&logoColor=white)](mailto:valknar@pivoine.art)
[![Network](https://img.shields.io/badge/NETWORK-FALCON__NETWORK-0077b6?style=for-the-badge&logo=docker&logoColor=white)](#)
[![Location](https://img.shields.io/badge/SECTOR-PIVOINE.ART-00b4d8?style=for-the-badge&logo=cloudflare&logoColor=white)](https://pivoine.art)

---

</div>

## 🌌 SHIP'S LOG

**STARDATE:** 2025.11.15
**LOCATION:** Deep Space, Uncharted Territories
**STATUS:** Captain currently engaged in... diplomatic relations with alien civilizations
**SYSTEMS:** All green, automated deployment active, CI/CD pipeline operational

> *"The Falcon doesn't just traverse the stars — it commands them."*
> — Captain Valknar, moments before jumping to hyperspace

---

## 🛸 VESSEL SPECIFICATIONS

The **Falcon** is a state-of-the-art containerized starship, powered by Docker's quantum drive engines and orchestrated through the legendary Arty navigation system.

### 🎯 CORE SYSTEMS

| **System** | **Purpose** | **Access Point** |
|:-----------|:------------|:-----------------|
| **SEXY** | *Advanced alien encounter database* | [sexy.pivoine.art](https://sexy.pivoine.art) |
| **AWSM** | *Intergalactic discovery catalog* | [awesome.pivoine.art](https://awesome.pivoine.art) |
| **TRACK** | *Mission analytics & telemetry* | [umami.pivoine.art](https://umami.pivoine.art) |
| **MATTERMOST** | *Crew collaboration & mission control* | [mattermost.pivoine.art](https://mattermost.pivoine.art) |
| **SCRAPY** | *Web scraping reconnaissance cluster* | [scrapy.pivoine.art](https://scrapy.pivoine.art) |
| **N8N** | *Automated workflow command center* | [n8n.pivoine.art](https://n8n.pivoine.art) |
| **STASH** | *Universal file management portal* | [stash.pivoine.art](https://stash.pivoine.art) |
| **LINKS** | *Interstellar bookmark archive* | [links.pivoine.art](https://links.pivoine.art) |
| **VAULT** | *Encrypted password vault* | [vault.pivoine.art](https://vault.pivoine.art) |
| **JOPLIN** | *Note-taking server & sync hub* | [joplin.pivoine.art](https://joplin.pivoine.art) |
| **KIT** | *Toolkit hub with converter, editor & colors* | [kit.pivoine.art](https://kit.pivoine.art) |
| **JELLY** | *Media streaming server* | [jelly.pivoine.art](https://jelly.pivoine.art) |
| **DROP** | *Peer-to-peer file sharing* | [drop.pivoine.art](https://drop.pivoine.art) |
| **AI** | *Claude AI with RAG & web scraping* | [ai.pivoine.art](https://ai.pivoine.art) |
| **RESTIC** | *Automated backup vault system* | [restic.pivoine.art](https://restic.pivoine.art) |
| **NETDATA** | *Real-time ship diagnostics & alerts* | [netdata.pivoine.art](https://netdata.pivoine.art) |
| **PROXY** | *Shield control dashboard* | [proxy.pivoine.art](https://proxy.pivoine.art) |
| **VPN** | *Cloaking device network* | [vpn.pivoine.art](https://vpn.pivoine.art) |
| **GITEA** | *Self-hosted Git & CI/CD platform* | [dev.pivoine.art](https://dev.pivoine.art) |
| **COOLIFY** | *Self-hosted deployment platform* | [coolify.dev.pivoine.art](https://coolify.dev.pivoine.art) |
| **ASCIINEMA** | *Terminal recording & sharing* | [asciinema.dev.pivoine.art](https://asciinema.dev.pivoine.art) |

### ⚙️ INFRASTRUCTURE

```
┌─────────────────────────────────────────────────┐
│  🛡️  TRAEFIK SHIELD GENERATOR (Proxy)          │
│  ├─ Auto-SSL via Let's Encrypt Reactor         │
│  ├─ HTTP → HTTPS Phase Shifters                │
│  ├─ Load Balancer Stabilizers                  │
│  ├─ Dashboard Command Center                   │
│  └─ Sablier Dynamic Scaling Plugin             │
├─────────────────────────────────────────────────┤
│  💾 POSTGRESQL 16 DATA CORE                    │
│  ├─ Directus Sector Database                   │
│  ├─ Umami Analytics Vault                      │
│  ├─ n8n Workflow Engine Database               │
│  ├─ Linkwarden Bookmark Archive                │
│  ├─ Joplin Note-taking Server Database         │
│  └─ Mattermost Team Chat Database              │
├─────────────────────────────────────────────────┤
│  🤖 AI INTELLIGENCE CORE (PostgreSQL 16)       │
│  ├─ pgvector extension for RAG operations      │
│  ├─ Open WebUI with Claude integration         │
│  ├─ Crawl4AI web scraping service              │
│  └─ Document embeddings & semantic search      │
├─────────────────────────────────────────────────┤
│  ⚡ REDIS CACHE HYPERDRIVE                     │
│  └─ Warp-speed data acceleration               │
├─────────────────────────────────────────────────┤
│  🔐 BACKREST BACKUP VAULT (Restic)             │
│  ├─ Automated volume snapshots                 │
│  ├─ Incremental backup engine                  │
│  └─ HiDrive remote repository                  │
└─────────────────────────────────────────────────┘
```

---

## 🚀 LAUNCH SEQUENCE

### Prerequisites
- Docker Engine v20+ installed
- Docker Compose v2.20+ installed
- Arty navigation system (`npm install -g arty` or `pnpm add -g arty`)
- Clearance level: **Captain**

### 🔧 Initialize Ship Systems

```bash
# Create the ship's neural network
arty net/create

# Launch all systems
arty up

# Monitor system status
arty ps

# Access ship's logs (real-time)
arty logs
```

### 📡 Individual System Control

```bash
# Power down specific systems
arty down

# Restart malfunctioning modules
arty restart

# Pull latest system updates from the mothership
arty pull

# Diagnostic report
arty config
```

---

## 💫 NAVIGATION COMMANDS

### Database Operations (SEXY Mission)

```bash
# Create database backup before alien encounter
arty db/dump

# Restore database after timeline anomaly
arty db/import

# Export exotic alien artifacts (uploads)
arty uploads/export

# Import artifacts to new timeline
arty uploads/import
```

### Deployment & Sync

```bash
# Synchronize .env to remote starbase
arty env/sync
```

### File Sharing (DROP System)

```bash
# Access PairDrop file sharing
# URL: https://drop.pivoine.art

# Features:
# - Peer-to-peer file transfers (WebRTC)
# - No server-side storage (direct device-to-device)
# - Works across different networks (STUN-enabled)
# - Share files, text, and clipboard content
# - Automatic device discovery
# - No account required

# How to use:
# 1. Open https://drop.pivoine.art on both devices
# 2. Devices will automatically discover each other
# 3. Click on discovered device to share files
# 4. Files transfer directly between devices (not through server)
```

### Media Streaming (JELLY System)

```bash
# Access Jellyfin media server
# URL: https://jelly.pivoine.art

# Features:
# - Stream photos and videos from HiDrive
# - Hardware transcoding support
# - Multi-device playback
# - Automatic metadata fetching
# - Compatible with mobile apps

# Media paths:
# - Photos: /mnt/hidrive/users/valknar/Pictures
# - Videos: /mnt/hidrive/users/valknar/Videos
```

### Toolkit (KIT System)

```bash
# Access unified toolkit (subdomain routing)

# Landing Page
# URL: https://kit.pivoine.art
# Main entry point with links to all toolkit services

# File Converter (Vert)
# URL: https://vert.kit.pivoine.art
# Features:
# - WebAssembly-based file conversion (250+ formats)
# - Images, audio, documents, video
# - Client-side processing (no uploads)
# - No file size limits

# Image Editor (Paint)
# URL: https://paint.kit.pivoine.art
# Features:
# - Browser-based image editing
# - Layer support
# - Filters, drawing tools, text, shapes
# - Supports PNG, JPG, GIF, WebP
# - Client-side processing (no uploads)

# Color Palette Generator (Pastel)
# URL: https://pastel.kit.pivoine.art
# API: https://pastel.kit.pivoine.art/api
# Features:
# - Generate beautiful color palettes
# - Color harmony algorithms
# - Interactive palette generation
# - Export in various formats
# - Programmatic API access
```

### AI Operations (AI System)

```bash
# Access Open WebUI with Claude integration
# URL: https://ai.pivoine.art

# Features:
# - ChatGPT-like interface with Claude AI
# - Upload documents for RAG (Retrieval-Augmented Generation)
# - Web search for current information
# - pgvector-powered semantic search
# - Email notifications via SMTP
# - n8n workflow integration

# How to use:
# 1. Visit https://ai.pivoine.art and create an account
# 2. In Settings → Connections, add Claude API:
#    - Name: Anthropic Claude
#    - API Base URL: https://api.anthropic.com/v1
#    - API Key: (your Anthropic API key)
# 3. Select Claude model in chat (claude-3-5-sonnet-20241022)
# 4. Upload documents in Knowledge → Files for RAG
# 5. Start chatting with AI-enhanced responses

# Internal services:
# - Crawl4AI scraping API: http://ai_crawl4ai:11235 (container network)
# - AI PostgreSQL with pgvector: ai_postgres:5432
# - Database: openwebui (user: ai)

# Integration with n8n:
# - Create workflows that use Crawl4AI for web scraping
# - Trigger AI tasks via webhooks
# - Send results to Mattermost notifications
```

### Backup Operations (RESTIC System)

```bash
# Access backup web interface
# URL: https://restic.pivoine.art
# Username: valknar
# Password: Set on first access

# View backup status
docker logs restic_app | grep scheduled

# Manually trigger backup for a specific plan
docker exec restic_app /backrest backup --plan postgres-backup

# List all snapshots in repository
docker exec restic_app restic -r /repos snapshots

# Restore from backup (via web UI recommended)
# Navigate to restic.pivoine.art → Browse snapshots → Restore files
```

**Automated Backup Schedule:**
- Daily backups: 2 AM - 8 AM (staggered by service)
- Weekly maintenance: Sundays at 2 AM (prune) and 3 AM (check)
- All volumes backed up to: `/mnt/hidrive/users/valknar/Backup`

---

## 🔄 CI/CD PIPELINE (GITEA ACTIONS)

The **SEXY** mission uses an automated build and deployment pipeline powered by Gitea Actions.

### 📦 Container Registry

**Image Source:** `dev.pivoine.art/valknar/sexy:latest`
**Registry:** Gitea Container Registry (self-hosted)

### ⚙️ Automated Workflow

```bash
# Workflow triggers on:
├─ Push to main/develop branches
├─ Git tags (v*.*.*)
├─ Pull requests (build only, no push)
└─ Manual workflow dispatch

# Build process:
1. Checkout repository
2. Set up Docker Buildx
3. Login to Gitea Container Registry
4. Extract metadata (tags, labels)
5. Build multi-platform image (linux/amd64)
6. Push to registry with cache optimization
7. Generate deployment summary
```

### 🏷️ Image Tagging Strategy

```yaml
# Automatic tags:
- latest              # Main branch builds
- develop             # Develop branch builds
- v1.2.3              # Semantic version tags
- v1.2                # Major.minor tags
- v1                  # Major version tags
- main-abc123         # Branch + commit SHA
```

### 🚀 Auto-Deployment

**Watchtower** monitors the registry and automatically updates containers when new images are pushed:

```bash
# Check interval: Every 5 minutes
# Update strategy: Rolling restart
# Label-based: Only updates containers with watchtower.enable=true

# Manual pull and restart:
ssh -A root@vps "cd ~/Projects/docker-compose && \
  docker pull dev.pivoine.art/valknar/sexy:latest && \
  arty up -d sexy_frontend"
```

### 🔑 Required Secrets

Configure in Gitea repository settings:

```bash
# Repository → Settings → Secrets
REGISTRY_TOKEN=<gitea_access_token_with_package_write_scope>
```

### 📊 Build Cache

Uses **registry cache** for faster builds:

```bash
# Cache location:
dev.pivoine.art/valknar/sexy:buildcache

# Benefits:
- Reuses Docker layers between builds
- Significantly faster rebuild times
- No GitHub Actions cache dependency
```

### 🛠️ Runner Configuration

**Gitea Runner:** `docker-runner`
**Labels:** ubuntu-latest, ubuntu-22.04, ubuntu-20.04
**Images:** catthehacker/ubuntu:act-* (with Docker pre-installed)
**Privileged Mode:** Enabled for Docker-in-Docker support

```bash
# View runner status:
ssh -A root@vps "docker logs dev_gitea_runner"

# Runner restart:
ssh -A root@vps "cd ~/Projects/docker-compose && arty restart gitea_runner"
```

---

## 🌠 SHIP ARCHITECTURE

```
THE FALCON (falcon_network)
│
├─ 🎯 CORE SERVICES
│  ├─ PostgreSQL 16      [Port 5432] → Data Vault
│  └─ Redis 7            [Internal]  → Cache Drive
│
├─ 🛡️ SECURITY LAYER
│  ├─ Traefik            [80/443]    → Shield Generator
│  ├─ Traefik Dashboard  [proxy.pivoine.art] → Control Center
│  └─ Sablier            [Internal]  → Scale-to-Zero Engine
│
├─ 🚀 APPLICATIONS
│  ├─ Directus API       [sexy.pivoine.art/api]
│  ├─ SvelteKit Frontend [sexy.pivoine.art]
│  ├─ Awesome Catalog    [awesome.pivoine.art]
│  ├─ Umami Analytics    [umami.pivoine.art]
│  ├─ Gotify Messenger   [gotify.pivoine.art]
│  ├─ Scrapyd Cluster    [scrapy.pivoine.art]
│  ├─ n8n Workflows      [n8n.pivoine.art]
│  ├─ Filestash Files    [stash.pivoine.art]
│  ├─ Linkwarden Marks   [links.pivoine.art]
│  ├─ Vaultwarden Vault  [vault.pivoine.art]
│  ├─ Joplin Sync Server [joplin.pivoine.art]
│  ├─ Kit Toolkit        [vert.kit.pivoine.art, paint.kit.pivoine.art, pastel.kit.pivoine.art]
│  ├─ Jellyfin Media     [jelly.pivoine.art]
│  ├─ PairDrop Sharing   [drop.pivoine.art]
│  ├─ Open WebUI AI      [ai.pivoine.art]
│  ├─ Backrest Backups   [restic.pivoine.art]
│  └─ WireGuard VPN      [vpn.pivoine.art]
│
├─ 🤖 AI INTELLIGENCE
│  ├─ PostgreSQL+pgvector [Internal] → Vector Database
│  ├─ Open WebUI         [ai.pivoine.art] → Claude Interface
│  └─ Crawl4AI           [Internal:11235] → Web Scraper
│
└─ 💾 STORAGE VOLUMES
   ├─ postgres_data      → Critical mission data
   ├─ directus_uploads   → Alien encounter evidence
   ├─ directus_bundle    → Custom modules
   ├─ awesome_data       → Discovery catalog
   ├─ scrapyd_data       → Web scraping archives
   ├─ scrapy_code        → Spider project code
   ├─ n8n_data           → Workflow configurations
   ├─ filestash_data     → File manager state
   ├─ linkwarden_data    → Bookmark archives
   ├─ meili_data         → Search index database
   ├─ vaultwarden_data   → Encrypted password vault
   ├─ joplin_data        → Note-taking server data
   ├─ jelly_config       → Jellyfin media server config
   ├─ ai_postgres_data   → AI vector database
   ├─ ai_webui_data      → Open WebUI application data
   ├─ ai_crawl4ai_data   → Web scraping cache
   ├─ backrest_data      → Backup system state
   ├─ backrest_config    → Backup configurations
   └─ letsencrypt_data   → Shield certificates
```

---

## 🎨 TECHNOLOGY STACK

<div align="center">

![Docker](https://img.shields.io/badge/DOCKER-2496ED?style=for-the-badge&logo=docker&logoColor=white)
![Traefik](https://img.shields.io/badge/TRAEFIK-00ADD8?style=for-the-badge&logo=traefikproxy&logoColor=white)
![PostgreSQL](https://img.shields.io/badge/POSTGRESQL-336791?style=for-the-badge&logo=postgresql&logoColor=white)
![Redis](https://img.shields.io/badge/REDIS-DC382D?style=for-the-badge&logo=redis&logoColor=white)
![Directus](https://img.shields.io/badge/DIRECTUS-6644FF?style=for-the-badge&logo=directus&logoColor=white)
![Svelte](https://img.shields.io/badge/SVELTE-FF3E00?style=for-the-badge&logo=svelte&logoColor=white)
![Next.js](https://img.shields.io/badge/NEXT.JS-000000?style=for-the-badge&logo=nextdotjs&logoColor=white)

</div>

---

## ⚠️ PROTOCOLS & SECURITY

```
🔐 ENCRYPTION STANDARD
├─ All transmissions encrypted via HTTPS
├─ Let's Encrypt quantum certificates
├─ TLS 1.2+ with strong cipher suites only
├─ HSTS enabled (1-year, preload ready)
└─ SNI strict mode enforced

🛡️ SECURITY HEADERS
├─ X-Frame-Options: SAMEORIGIN
├─ X-XSS-Protection enabled
├─ Content-Type-Options: nosniff
├─ Referrer-Policy configured
└─ Permissions-Policy restrictions

🔒 ACCESS CONTROL
├─ Admin credentials in .env vault
├─ Database authentication: scram-sha-256
├─ HTTP Basic Auth on sensitive endpoints
├─ Rate limiting available (100 req/s)
└─ VPN cloaking device enabled

💾 BACKUP PROTOCOL
├─ Automated daily backups (2-10 AM)
├─ 16 backup plans covering all volumes
├─ Retention: 7 daily, 4 weekly, 3-12 monthly
├─ Encrypted restic repositories
├─ Weekly maintenance (prune & integrity check)
├─ Web UI for monitoring & restore
└─ HiDrive remote storage
```

---

## 📊 MISSION STATUS

```
╔════════════════════════════════════════╗
║  SHIP'S VITAL SIGNS                    ║
╠════════════════════════════════════════╣
║  ✅ Core Systems       → OPERATIONAL   ║
║  ✅ Shield Generator   → ONLINE        ║
║  ✅ Database Vault     → SECURED       ║
║  ✅ Cache Drive        → OPTIMIZED     ║
║  ✅ Backup System      → AUTOMATED     ║
║  🌟 Captain Status     → ON ADVENTURE  ║
╚════════════════════════════════════════╝

Next Backup: Tomorrow 2:00 AM (postgres-backup)
Backup Target: /mnt/hidrive/users/valknar/Backup
Repository Status: Initialized & Ready
```

---

## 👽 CAPTAIN'S NOTES

*Currently out exploring the cosmos and making friends with alien species. You know how it is — one minute you're charting a nebula, the next you're at an intergalactic party.*

*If systems malfunction, check the logs. If things are really bad, I left a backup captain AI (it's called documentation).*

*Stay shiny, crew. Valknar out.*

---

## 📡 TRANSMISSION CHANNELS

- 🌐 **Flagship:** [pivoine.art](https://pivoine.art)
- 📧 **Subspace Mail:** valknar@pivoine.art
- 🚀 **Mission Control:** [sexy.pivoine.art](https://sexy.pivoine.art)
- 📊 **Analytics Bay:** [umami.pivoine.art](https://umami.pivoine.art)

---

<div align="center">

```
╔═══════════════════════════════════════════════════════════╗
║                                                           ║
║     "In space, no one can hear you `docker compose up`"   ║
║                                                           ║
║              — Captain Valknar, The Falcon                ║
║                                                           ║
╚═══════════════════════════════════════════════════════════╝
```

![Made with Docker](https://img.shields.io/badge/POWERED_BY-DOCKER_COMPOSE-0db7ed?style=for-the-badge&logo=docker&logoColor=white)
![Arty](https://img.shields.io/badge/NAVIGATED_BY-ARTY-4169e1?style=for-the-badge&logo=npm&logoColor=white)
![Captain](https://img.shields.io/badge/COMMANDED_BY-VALKNAR-silver?style=for-the-badge&logo=linux&logoColor=white)

**THE FALCON** • *Fastest ship in the Docker registry* • **EST. 2025**

</div>