docker-compose.yml

# ═══════════════════════════════════════════════════════════════════════════════
# Ghost Narrator - Audio Pipeline Services
# ═══════════════════════════════════════════════════════════════════════════════
#
# Services:
#   - redis: Job state persistence
#   - n8n: Workflow orchestration
#   - tts-service: Studio-quality TTS API (Qwen3-TTS)
#   - ollama: Bundled LLM for cpu_only / low_vram tiers  (profile: cpu)
#   - vllm:   Bundled LLM for mid_vram / high_vram tiers (profile: gpu)
#
# LLM backend selection (set by install.sh, stored in .env):
#   cpu_only / low_vram (no GPU or < 12 GB VRAM)  →  COMPOSE_PROFILES=cpu  LLM_BASE_URL=http://ollama:11434/v1
#   mid_vram / high_vram (≥ 12 GB VRAM)           →  COMPOSE_PROFILES=gpu  LLM_BASE_URL=http://vllm:8000/v1
#
# Usage:
#   docker compose up -d
#   docker compose logs -f tts-service
#
# Environment Variables (required in .env):
#   - SERVER_EXTERNAL_IP: External IP for webhook URLs
#   - N8N_USER: n8n admin username
#   - N8N_PASSWORD: n8n admin password
#   - N8N_ENCRYPTION_KEY: n8n encryption key (openssl rand -hex 32)
#   - GCS_BUCKET_NAME: GCS bucket for audio storage (STORAGE_BACKEND=gcs)
#   - LLM_BASE_URL: set by install.sh; override for external OpenAI-compatible API
#   - COMPOSE_PROFILES: set by install.sh; controls which LLM backend starts
#
# ═══════════════════════════════════════════════════════════════════════════════

services:
  # ─── Hardware Probe: Tier Detection (init, runs once) ─────────────────────
  hardware-probe:
    image: alpine:3.19
    container_name: hardware-probe
    restart: "no"
    environment:
      - HARDWARE_TIER=${HARDWARE_TIER:-}
      - SELECTED_TTS_MODEL=${SELECTED_TTS_MODEL:-}
      - SELECTED_LLM_MODEL=${SELECTED_LLM_MODEL:-}
      - SELECTED_LLM_NUM_CTX=${SELECTED_LLM_NUM_CTX:-}
    volumes:
      - ./scripts/init/hardware-probe.sh:/scripts/hardware-probe.sh:ro
      - tier_data:/shared
    entrypoint: ["/bin/sh", "/scripts/hardware-probe.sh"]

  # ─── Redis: Job State Persistence ────────────────────────────────────────────
  redis:
    image: redis:7-alpine
    container_name: redis
    restart: unless-stopped
    # Port 6379 intentionally NOT published to host — Redis has no other auth layer.
    # Access it from within the Docker network only (pipeline_net).
    command: >
      redis-server
      --appendonly yes
      --appendfsync everysec
      --maxmemory 512mb
      --maxmemory-policy volatile-lru
      --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    networks:
      - pipeline_net
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 128M

  # ─── Ollama: Bundled LLM for cpu_only / low_vram tiers ───────────────────────
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    profiles: [cpu]
    ports:
      - "11434:11434"
    environment:
      - SHARED_DIR=/shared
      # Raise the per-request timeout above the hardcoded 120s limit in Ollama
      # 0.20.x — long articles (7000+ words) at 9B model speed exceed it.
      - OLLAMA_REQUEST_TIMEOUT=600
      - LLM_MODEL_NAME=${LLM_MODEL_NAME:-}
    volumes:
      - ollama_models:/root/.ollama
      - tier_data:/shared:ro
      - ./scripts/init/ollama-init.sh:/scripts/ollama-init.sh:ro
    entrypoint: ["/bin/sh", "/scripts/ollama-init.sh"]
    networks:
      - pipeline_net
    depends_on:
      hardware-probe:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "ollama", "list"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 600s
    deploy:
      resources:
        limits:
          memory: 12G
        reservations:
          memory: 2G

  # ─── vLLM: Bundled LLM for mid_vram / high_vram GPU tiers ────────────────────
  vllm:
    image: vllm/vllm-openai:latest
    container_name: vllm
    restart: unless-stopped
    profiles: [gpu]
    ports:
      - "8000:8000"
    ipc: host
    environment:
      - SHARED_DIR=/shared
      - HF_HOME=/root/.cache/huggingface
      # More accurate CUDA graph memory accounting during KV cache profiling.
      # Frees the ~33 MB that the old profiler over-reserved for CUDA graphs.
      - VLLM_MEMORY_PROFILER_ESTIMATE_CUDAGRAPHS=1
    volumes:
      - vllm_models:/root/.cache/huggingface
      - tier_data:/shared:ro
      - ./scripts/init/vllm-init.sh:/scripts/vllm-init.sh:ro
    entrypoint: ["/bin/sh", "/scripts/vllm-init.sh"]
    networks:
      - pipeline_net
    depends_on:
      hardware-probe:
        condition: service_completed_successfully
    healthcheck:
      test:
        [
          "CMD",
          "python3",
          "-c",
          "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')",
        ]
      interval: 30s
      timeout: 10s
      retries: 10
      start_period: 1200s
    deploy:
      resources:
        limits:
          memory: 30G
        reservations:
          memory: 8G

  # ─── n8n: Workflow Orchestration ─────────────────────────────────────────────
  n8n:
    image: n8nio/n8n:1.123.30
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      # Authentication (n8n v1.x — N8N_BASIC_AUTH_* was removed in v1.0)
      # N8N_OWNER_EMAIL/PASSWORD auto-configure the owner account on first start,
      # skipping the setup wizard. N8N_USER in .env should be a valid email address.
      - N8N_OWNER_EMAIL=${N8N_USER}
      - N8N_OWNER_PASSWORD=${N8N_PASSWORD}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      # Disable secure cookie for HTTP access (set to true if using HTTPS)
      - N8N_SECURE_COOKIE=false
      # Allow env var access in workflow expressions
      - N8N_BLOCK_ENV_ACCESS_IN_NODE=false
      - NODE_FUNCTION_ALLOW_BUILTIN=crypto
      # Server configuration
      - WEBHOOK_URL=http://${SERVER_EXTERNAL_IP}:5678/
      - N8N_HOST=0.0.0.0
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      # Database
      - DB_TYPE=sqlite
      - DB_SQLITE_VACUUM_ON_STARTUP=true
      # SQLite read-connection pool. Without this, n8n's
      # LegacySqliteExecutionRecoveryService races startup migrations
      # under contention, the DB connection times out, and the cleanup
      # assertion fires ("must be connected and migrated"), crash-looping
      # the container. Setting a pool size >= 1 serialises reads behind
      # the migration lock and resolves the race.
      - DB_SQLITE_POOL_SIZE=4
      # Execution history pruning — prevents SQLite from growing unbounded
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=168
      - EXECUTIONS_DATA_PRUNE_MAX_COUNT=1000
      # Binary data on filesystem so large payloads don't bloat the V8 heap
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
      # Raise the payload limit to handle large article HTML (default is 16MB)
      - N8N_PAYLOAD_SIZE_MAX=50
      # Cap Node.js V8 old-space heap to 1536MB — must stay below the container
      # memory limit (2GB) to avoid silent OOM kills
      - NODE_OPTIONS=--max-old-space-size=1536
      # Limit concurrent workflow executions — prevents memory spikes when a
      # backfill run overlaps with a live Ghost publish webhook
      - N8N_CONCURRENCY_PRODUCTION_LIMIT=10
      # Logging
      - N8N_LOG_LEVEL=info
      # Timezone
      - GENERIC_TIMEZONE=${TIMEZONE:-UTC}
      # External services (passed to workflow)
      - LLM_BASE_URL=${LLM_BASE_URL:-http://ollama:11434/v1}
      - LLM_MODEL_NAME=${LLM_MODEL_NAME:-}
      - TTS_SERVICE_URL=http://tts-service:8020
      - TTS_API_KEY=${TTS_API_KEY}
      # Ghost API Keys (for fetching article content and updating posts)
      - GHOST_SITE1_URL=${GHOST_SITE1_URL:-}
      - GHOST_SITE2_URL=${GHOST_SITE2_URL:-}
      - GHOST_KEY_SITE1=${GHOST_KEY_SITE1:-}
      - GHOST_KEY_SITE2=${GHOST_KEY_SITE2:-}
      - GHOST_SITE1_ADMIN_API_KEY=${GHOST_SITE1_ADMIN_API_KEY:-}
      - GHOST_SITE2_ADMIN_API_KEY=${GHOST_SITE2_ADMIN_API_KEY:-}
    volumes:
      - n8n_data:/home/node/.n8n
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - pipeline_net
    depends_on:
      redis:
        condition: service_healthy
      tts-service:
        condition: service_healthy
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.25'
          memory: 1G

  # ─── TTS Service: Studio-Quality API ──────────────────────────────────────────
  tts-service:
    build:
      context: ./tts-service
      dockerfile: Dockerfile
    image: ghost-tts-service:latest
    container_name: tts-service
    restart: unless-stopped
    ports:
      - "8020:8020"
    environment:
      # PyTorch CUDA allocator: expandable segments instead of fixed pools.
      # Without this, long jobs (40+ segments) accumulate fragmentation —
      # 100s of MiB sit "reserved but unallocated" in scattered fragments
      # while a small allocation can't find a single contiguous slot, even
      # though aggregate free memory is sufficient. Cost is negligible on
      # modern PyTorch; harmless on CPU tiers (the var is CUDA-only).
      - PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
      # TTS configuration
      - VOICE_SAMPLE_PATH=/app/voices/default/reference.wav
      # Optional: transcription of your reference audio for higher-quality ICL cloning.
      # Leave blank to use x-vector-only mode (no transcription needed).
      - VOICE_SAMPLE_REF_TEXT=${VOICE_SAMPLE_REF_TEXT:-}
      - TTS_LANGUAGE=${TTS_LANGUAGE:-auto}
      # Acoustic gate: set false to enforce rejection, true for shadow/calibration mode.
      # Default false — dry-run requires explicit opt-in, not the other way around.
      - DRY_RUN_GATE=${DRY_RUN_GATE:-false}
      - HARDWARE_TIER=${HARDWARE_TIER:-}
      - SELECTED_LLM_NUM_CTX=${SELECTED_LLM_NUM_CTX:-}
      # MAX_WORKERS is used for CPU mode parallel synthesis
      - MAX_WORKERS=${MAX_WORKERS:-4}
      # Studio segment sizing — leave blank to use the active tier default
      # (CPU 100 / LOW 80 / MID 70 / HIGH 60). Clamped to 30-300.
      - SINGLE_SHOT_SEGMENT_WORDS=${SINGLE_SHOT_SEGMENT_WORDS:-}
      - SINGLE_SHOT_OVERLAP_MS=${SINGLE_SHOT_OVERLAP_MS:-500}
      # Audio quality — leave blank to use hardware-tier defaults
      - MP3_BITRATE=${MP3_BITRATE:-}
      - AUDIO_SAMPLE_RATE=${AUDIO_SAMPLE_RATE:-}
      - TARGET_LUFS=${TARGET_LUFS:-}
      # Google Cloud Storage
      - GCS_BUCKET_NAME=${GCS_BUCKET_NAME:-}
      - GCS_AUDIO_PREFIX=${GCS_AUDIO_PREFIX:-audio/articles}
      # n8n callback webhook
      - N8N_CALLBACK_URL=http://n8n:5678/webhook/tts-callback
      # Redis job store
      - REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379/0
      - REDIS_JOB_TTL=${REDIS_JOB_TTL:-86400}
      - MAX_JOB_DURATION_SECONDS=${MAX_JOB_DURATION_SECONDS:-28800}
      - STORAGE_BACKEND=${STORAGE_BACKEND:-local}
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}
      - AWS_REGION=${AWS_REGION:-us-east-1}
      - S3_BUCKET_NAME=${S3_BUCKET_NAME:-}
      - S3_AUDIO_PREFIX=${S3_AUDIO_PREFIX:-audio/articles}
      - GCS_SERVICE_ACCOUNT_KEY_PATH=${GCS_SERVICE_ACCOUNT_KEY_PATH:-}
      - LLM_BASE_URL=${LLM_BASE_URL:-http://ollama:11434/v1}
      # Leave blank to use the hardware-tier default from ENGINE_CONFIG (e.g. qwen3.5:2b,
      # Qwen/Qwen3.5-9B). Set explicitly only to override the tier selection.
      - LLM_MODEL_NAME=${LLM_MODEL_NAME:-}
      - SERVER_EXTERNAL_IP=${SERVER_EXTERNAL_IP:-localhost}
      - TTS_API_KEY=${TTS_API_KEY}
      - LLM_API_KEY=${LLM_API_KEY:-ollama}
      - TRUSTED_PROXY_COUNT=${TRUSTED_PROXY_COUNT:-0}
      - LLM_TIMEOUT=${LLM_TIMEOUT:-300}
      - LLM_COMPLETENESS_TIMEOUT=${LLM_COMPLETENESS_TIMEOUT:-360}
      - LOG_FORMAT=${LOG_FORMAT:-}
      - LOG_LEVEL=${LOG_LEVEL:-INFO}
      - OTEL_SERVICE_NAME=ghost-narrator-tts
      - OTEL_EXPORTER_OTLP_ENDPOINT=${OTEL_EXPORTER_OTLP_ENDPOINT:-}
    volumes:
      - ./tts-service/voices:/app/voices
      - tts_output:/app/output
      - tier_data:/shared:ro
      - ./secrets:/app/secrets:ro
    networks:
      - pipeline_net
    depends_on:
      hardware-probe:
        condition: service_completed_successfully
      redis:
        condition: service_healthy
    healthcheck:
      test:
        [
          "CMD",
          "python",
          "-c",
          "import urllib.request; urllib.request.urlopen('http://localhost:8020/health')",
        ]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 300s
    deploy:
      resources:
        limits:
          memory: 6G
        reservations:
          memory: 4G

# ─── Volumes ───────────────────────────────────────────────────────────────────
volumes:
  redis_data:
    driver: local
  n8n_data:
    driver: local
  tts_output:
    driver: local
  tier_data:
    driver: local
  ollama_models:
    driver: local
  vllm_models:
    driver: local

# ─── Networks ──────────────────────────────────────────────────────────────────
networks:
  pipeline_net:
    driver: bridge