siftlode/docker-compose.home.yml.example

# Home deployment — the app + database run on the home server (a Proxmox LXC), and a small
# public VPS reverse-proxies the public hostname to it over a private WireGuard tunnel. This
# keeps the heavy work (full-catalog feed/count/facet scans) on strong, always-on home
# hardware while the VPS stays a thin, cheap public endpoint.
#
# Differences from docker-compose.prod.yml (the bare-VPS stack): runs as Docker-in-LXC
# (security_opt apparmor:unconfined), Postgres gets real RAM + tuning so the catalog stays
# hot in cache, and the api is published on the LXC (reachable only via the WireGuard peer /
# trusted LAN — never port-forwarded to the public internet; the VPS Caddy is the public TLS
# front door, so the OAuth redirect URL is unchanged).
#
# Deploy (from the build box, over the LAN):
#   cd /docker && docker compose -f docker-compose.home.yml --env-file .env pull && \
#     docker compose -f docker-compose.home.yml --env-file .env up -d
#
# Required keys in /docker/.env: POSTGRES_PASSWORD, SECRET_KEY (>=32 chars),
# TOKEN_ENCRYPTION_KEY (Fernet), GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET,
# OAUTH_REDIRECT_URL=https://siftlode.example.com/auth/callback, ALLOWED_EMAILS, ADMIN_EMAILS,
# YOUTUBE_API_KEY. APP_VERSION is exported by the deploy step (selects the image tag).
# Optional: DOWNLOAD_HOST_PATH (host dir for the download tree) and PLEX_MEDIA_HOST_PATH (host dir
# holding the Plex library, mounted read-only for the optional Plex module).

name: siftlode

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-siftlode}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set in the env file}
      POSTGRES_DB: ${POSTGRES_DB:-siftlode}
    # Tuned for the home box (plenty of RAM): keep the ~350 MB catalog hot in shared_buffers,
    # tell the planner about the large OS cache, give sorts headroom, and price random access
    # like an SSD so index plans aren't penalised. (See the feed EXPLAIN analysis.)
    command:
      - postgres
      - -c
      - shared_buffers=1GB
      - -c
      - effective_cache_size=4GB
      - -c
      - work_mem=32MB
      - -c
      - maintenance_work_mem=256MB
      - -c
      - random_page_cost=1.1
      - -c
      - max_parallel_workers_per_gather=2
    volumes:
      - siftlode_pgdata:/var/lib/postgresql/data
    networks: [internal]
    mem_limit: 4g
    cpus: 3.0
    security_opt:
      - no-new-privileges:true
      - apparmor:unconfined
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-siftlode} -d ${POSTGRES_DB:-siftlode}"]
      interval: 10s
      timeout: 5s
      retries: 12
    restart: unless-stopped

  api:
    # Pulled prebuilt image published by `siftlode publish`; the tag follows the released
    # VERSION (the deploy step exports APP_VERSION). No build on the host.
    image: registry.example.com/you/siftlode:${APP_VERSION:-latest}
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-siftlode}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB:-siftlode}
      # The public instance owns the background scheduler (single writer).
      SCHEDULER_ENABLED: "true"
      # Download center: the API serves finished files + builds filmstrips (read-only root is fine —
      # it only writes to the /downloads mount + tmpfs). The yt-dlp job loop runs in `worker` below.
      DOWNLOAD_ROOT: /downloads
      WORKER_ENABLED: "false"
    depends_on:
      db:
        condition: service_healthy
    networks: [internal]
    ports:
      # Published on the LXC. Reached by the VPS Caddy over the WireGuard tunnel
      # (10.x.x.x:8080) and on the trusted home LAN. Never forwarded to the public internet.
      - "8080:8000"
    volumes:
      # Downloaded media. Defaults to a Docker-managed named volume; set DOWNLOAD_HOST_PATH in .env
      # to a host directory (e.g. one your Plex server reads) to keep the Plex-style tree there.
      - ${DOWNLOAD_HOST_PATH:-siftlode_downloads}:/downloads
      # Plex media, read-only. Only used when the optional Plex module is enabled: set
      # PLEX_MEDIA_HOST_PATH in .env to the host directory holding the Plex library (the local side
      # of plex_path_map, default /plex-media). Left unset → an empty named volume (harmless; the
      # Plex module is off by default). On this home stack (LXC on the Plex host) it's a plain host
      # bind-mount — no SMB (that's the localdev-only path).
      - ${PLEX_MEDIA_HOST_PATH:-siftlode_plex_media}:/plex-media:ro
    mem_limit: 1536m
    cpus: 2.0
    pids_limit: 512
    security_opt:
      - no-new-privileges:true
      - apparmor:unconfined
    cap_drop:
      - ALL
    read_only: true
    tmpfs:
      - /tmp
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/healthz').status==200 else 1)"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 30s
    restart: unless-stopped

  # Download worker: same image, runs the yt-dlp / ffmpeg job loop instead of the API. Shares the
  # DB (job queue) and the downloads mount with the API. Not read-only (yt-dlp/deno/ffmpeg write to
  # $HOME caches + the staging dir); heavier limits since it does the video encoding.
  worker:
    image: registry.example.com/you/siftlode:${APP_VERSION:-latest}
    command: ["python", "-m", "app.worker"]
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-siftlode}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB:-siftlode}
      # The API owns the scheduler; the worker must not also run it.
      SCHEDULER_ENABLED: "false"
      DOWNLOAD_ROOT: /downloads
      WORKER_ENABLED: "true"
    depends_on:
      db:
        condition: service_healthy
      # Start only after the API is healthy — it applies the DB migrations on its own startup,
      # so this guarantees the download tables exist before the worker touches them.
      api:
        condition: service_healthy
      bgutil-pot:
        condition: service_started
    networks: [internal]
    volumes:
      - ${DOWNLOAD_HOST_PATH:-siftlode_downloads}:/downloads
      # Plex media (read-only) — same mount as the api; used by Plex clip jobs (a later phase).
      - ${PLEX_MEDIA_HOST_PATH:-siftlode_plex_media}:/plex-media:ro
    mem_limit: 2g
    cpus: 2.0
    pids_limit: 512
    security_opt:
      - no-new-privileges:true
      - apparmor:unconfined
    cap_drop:
      - ALL
    tmpfs:
      - /tmp
    restart: unless-stopped

  # PO-token provider sidecar: mints YouTube Proof-of-Origin tokens on demand so the worker beats
  # bot-detection + unlocks high-quality formats. The worker reaches it at http://bgutil-pot:4416
  # (config default). Pin the tag to the plugin version in requirements.txt.
  bgutil-pot:
    image: brainicism/bgutil-ytdlp-pot-provider:1.3.1
    init: true
    networks: [internal]
    mem_limit: 512m
    security_opt:
      - no-new-privileges:true
      - apparmor:unconfined
    restart: unless-stopped

volumes:
  siftlode_pgdata:
  siftlode_downloads:
  # Empty fallback for the Plex media mount when PLEX_MEDIA_HOST_PATH is unset (Plex module off).
  siftlode_plex_media:

networks:
  internal: