docker-compose/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Multi-service Docker Compose stack named "falcon" managing production services on pivoine.art domain. Uses Arty for configuration management with centralized environment variables and custom scripts.

Architecture

Compose Include Pattern

Root compose.yaml uses Docker Compose's include directive to orchestrate multiple service stacks:

• core: Shared PostgreSQL 16 + Redis 7 infrastructure
• proxy: Traefik reverse proxy with Let's Encrypt SSL
• sexy: Directus 11 CMS + SvelteKit frontend
• awsm: Next.js application with SQLite
• track: Umami analytics (PostgreSQL)
• gotify: Push notification server
• scrapy: Scrapyd web scraping cluster (scrapyd, scrapy, scrapyrt)
• n8n: Workflow automation platform (PostgreSQL)
• stash: Filestash web-based file manager
• vpn: WireGuard VPN (wg-easy)

All services connect to a single external Docker network (falcon_network by default, defined by $NETWORK_NAME).

Environment Management via Arty

Configuration is centralized in arty.yml:

• envs.default: All environment variables with sensible defaults
• scripts: Common Docker Compose and operational commands
• Variables follow naming pattern: {SERVICE}_COMPOSE_PROJECT_NAME, {SERVICE}_TRAEFIK_HOST, etc.

Sensitive values (passwords, secrets) live in .env and override arty.yml defaults.

Traefik Routing Architecture

Services expose themselves via Docker labels:

• HTTP → HTTPS redirect on web entrypoint (port 80)
• SSL termination on web-secure entrypoint (port 443)
• Let's Encrypt certificates stored in proxy volume
• Path-based routing: /api routes to Directus backend, root to frontend
• Compression middleware applied via labels
• All routers scoped to $NETWORK_NAME network

Database Initialization

core/postgres/init/01-init-databases.sh runs on first PostgreSQL startup:

• Creates directus database for Sexy CMS
• Creates umami database for Track analytics
• Creates n8n database for workflow automation
• Grants privileges to $DB_USER

Common Commands

All commands use pnpm arty (leveraging scripts in arty.yml):

Stack Management

# Start all services
pnpm arty up

# Stop all services
pnpm arty down

# View running containers
pnpm arty ps

# Follow logs for all services
pnpm arty logs

# Restart all services
pnpm arty restart

# Pull latest images
pnpm arty pull

# View rendered configuration (with variables substituted)
pnpm arty config

Network Setup

# Create external Docker network (required before first up)
pnpm arty net/create

Database Operations (Sexy/Directus)

# Export Directus database + schema snapshot
pnpm arty db/dump

# Import database dump + apply schema snapshot
pnpm arty db/import

# Export Directus uploads directory
pnpm arty uploads/export

# Import Directus uploads directory
pnpm arty uploads/import

Deployment

# Sync .env file to remote VPS
pnpm arty env/sync

Service-Specific Details

Core Services (core/compose.yaml)

• postgres: PostgreSQL 16 Alpine, exposed on host port 5432
  • Uses scram-sha-256 authentication
  • Health check via pg_isready
  • Init scripts mounted from ./postgres/init/
• redis: Redis 7 Alpine for caching
  • Used by Directus for cache and websocket storage

Sexy (sexy/compose.yaml)

Directus headless CMS + SvelteKit frontend:

• directus: Directus 11.12.0
  • Admin panel + GraphQL/REST API
  • Traefik routes /api path to port 8055
  • Volumes: directus_uploads for media, directus_bundle for extensions
  • Email via SMTP (IONOS configuration in .env)
• frontend: Custom SvelteKit app from ghcr.io/valknarxxx/sexy
  • Serves on port 3000
  • Shared directus_bundle volume for Directus extensions

Proxy (proxy/compose.yaml)

Traefik 3.x reverse proxy:

• Global HTTP→HTTPS redirect
• Let's Encrypt via TLS challenge
• Dashboard disabled (api.dashboard=false)
• Reads labels from Docker socket (/var/run/docker.sock)
• Scoped to $NETWORK_NAME network via provider configuration

AWSM (awsm/compose.yaml)

Next.js app with embedded SQLite:

• Serves awesome-app list directory
• Optional GitHub token for API rate limits
• Optional webhook secret for database updates
• Database persisted in awesome_data volume

Scrapy (scrapy/compose.yaml)

Web scraping cluster with three services:

• scrapyd: Scrapyd daemon exposed at scrapy.pivoine.art:6800
  • Web interface for deploying and managing spiders
  • Data persisted in scrapyd_data volume
• scrapy: Development container for running Scrapy commands
  • Shared scrapy_code volume for spider projects
• scrapyrt: Scrapyd Real-Time API on port 9080
  • Run spiders via HTTP API without scheduling

n8n (n8n/compose.yaml)

Workflow automation platform:

• n8n: n8n application exposed at n8n.pivoine.art:5678
  • Visual workflow builder with 200+ integrations
  • PostgreSQL backend for workflow persistence
  • Runners enabled for task execution
  • Webhook support for external triggers
  • Data persisted in n8n_data volume

Stash (stash/compose.yaml)

Web-based file manager:

• filestash: Filestash app exposed at stash.pivoine.art:8334
  • Support for multiple storage backends (SFTP, S3, Dropbox, Google Drive, FTP, WebDAV)
  • In-browser file viewer and media player
  • File sharing capabilities
  • Data persisted in filestash_data volume

Important Environment Variables

Key variables defined in arty.yml and overridden in .env:

• NETWORK_NAME: Docker network name (default: falcon_network)
• ADMIN_EMAIL: Used for Let's Encrypt and service admin accounts
• DB_USER, DB_PASSWORD: PostgreSQL credentials
• CORE_DB_HOST, CORE_DB_PORT: PostgreSQL connection (default: postgres:5432)
• CORE_REDIS_HOST, CORE_REDIS_PORT: Redis connection (default: redis:6379)
• {SERVICE}_TRAEFIK_HOST: Domain for each service
• {SERVICE}_TRAEFIK_ENABLED: Toggle Traefik exposure
• SEXY_DIRECTUS_SECRET: Directus security secret
• TRACK_APP_SECRET: Umami analytics secret

Volume Management

Each service uses named volumes prefixed with project name:

• core_postgres_data, core_redis_data: Database persistence
• core_directus_uploads, core_directus_bundle: Directus media/extensions
• awesome_data: AWSM SQLite database
• scrapy_scrapyd_data, scrapy_scrapy_code: Scrapy spider data and code
• n8n_n8n_data: n8n workflow data
• stash_filestash_data: Filestash configuration and state
• proxy_letsencrypt_data: SSL certificates

Volumes can be inspected with:

docker volume ls | grep falcon
docker volume inspect <volume_name>

Troubleshooting

Services won't start

1. Ensure external network exists: pnpm arty net/create
2. Check if services reference correct $NETWORK_NAME in labels
3. Verify .env has required secrets (compare with arty.yml envs.default)

SSL certificates failing

1. Check ADMIN_EMAIL is set in .env
2. Ensure ports 80/443 are accessible from internet
3. Inspect Traefik logs: docker logs proxy_app

Database connection errors

1. Check PostgreSQL is healthy: docker ps (should show healthy status)
2. Verify database exists: docker exec core_postgres psql -U $DB_USER -l
3. Check credentials match between .env and service configs

Directus schema migration

• Export schema: pnpm arty db/dump (creates sexy/directus.yaml)
• Import to new instance: pnpm arty db/import (applies schema snapshot)
• Schema file stored in sexy/directus.yaml for version control