pounce/SERVER_DEPLOYMENT.md

Server Deployment (Docker Compose)

Ziel

Pounce auf einem Server starten mit:

• Frontend (Next.js)
• Backend API (FastAPI)
• Postgres
• Redis (Rate-Limit Storage + Job Queue)
• Scheduler (APScheduler) – separater Prozess
• Worker (ARQ) – separater Prozess

Damit laufen Jobs nicht mehrfach bei mehreren API-Workern und die UI bleibt schnell.

---

Voraussetzungen

• Linux Server (z.B. Ubuntu 22.04+)
• Docker + Docker Compose Plugin
• Domain + HTTPS Reverse Proxy (empfohlen), damit Cookie-Auth zuverlässig funktioniert

---

1) Repo auf den Server holen

cd /opt
git clone <your-repo-url> pounce
cd pounce

---

2) Server-Environment anlegen

In /opt/pounce:

cp DEPLOY_docker_compose.env.example .env

Dann .env öffnen und mindestens setzen:

• DB_PASSWORD
• SECRET_KEY
• SITE_URL (z.B. https://pounce.example.com)
• ALLOWED_ORIGINS (z.B. https://pounce.example.com)

Optional (aber empfohlen):

• SMTP_* (für Alerts/Emails)
• COOKIE_DOMAIN (wenn du Cookies über Subdomains teilen willst)

---

3) Starten

docker compose up -d --build

Services:

• frontend (Port 3000)
• backend (Port 8000)
• scheduler (kein Port)
• worker (kein Port)
• db (kein Port)
• redis (kein Port)

---

4) Initial Setup (1× nach erstem Start)

DB Tabellen + Baseline Seed

docker compose exec backend python scripts/init_db.py

TLD Price Seed (886+)

docker compose exec backend python scripts/seed_tld_prices.py

---

5) Reverse Proxy (empfohlen)

Warum?

Das Frontend ruft im Browser standardmässig https://<domain>/api/v1/... auf (same-origin).
Darum solltest du:

• HTTPS terminieren
• /api/v1/* an das Backend routen
• / an das Frontend routen

Beispiel: Caddy (sehr simpel)

pounce.example.com {
  encode zstd gzip

  # API
  handle_path /api/v1/* {
    reverse_proxy 127.0.0.1:8000
  }

  # Frontend
  reverse_proxy 127.0.0.1:3000

  # optional: metrics nur intern
  @metrics path /metrics
  handle @metrics {
    respond 403
  }
}

Wichtig:

• Setze SITE_URL=https://pounce.example.com
• Setze COOKIE_SECURE=true (oder via ENVIRONMENT=production)

---

6) Checks (nach Deploy)

curl -f http://127.0.0.1:8000/health
curl -f http://127.0.0.1:8000/metrics

Logs:

docker compose logs -f backend
docker compose logs -f scheduler
docker compose logs -f worker

---

7) Updates

cd /opt/pounce
git pull
docker compose up -d --build

---

Troubleshooting (häufig)

• Cookies/Login klappt nicht:
  • Prüfe SITE_URL und HTTPS (Secure Cookies)
  • Prüfe ALLOWED_ORIGINS (falls Frontend/Backend nicht same-origin sind)
• Scheduler läuft doppelt:
  • Stelle sicher, dass nur ein scheduler Service läuft (keine zweite Instanz)
• Emails werden nicht gesendet:
  • docker compose exec scheduler env | grep SMTP_
  • SMTP Vars müssen im Container vorhanden sein (kommen aus .env)