plm-lottery/docs/running-the-server.md

Avviare il server

Presuppone che setup.md sia già stato completato (.env pronto, master key generata, migrazioni applicate).

Locale / venv (sviluppo rapido)

source .venv/bin/activate
uvicorn app.main:app --reload --port 8123

• App su http://127.0.0.1:8123/
• Pannello admin su http://127.0.0.1:8123/admin
• Docs API interattive su http://127.0.0.1:8123/docs solo se ENABLE_API_DOCS=true in .env — disattivate di default perché espongono l'intera API, endpoint admin inclusi (vedi setup.md)
• Log applicativi in logs/app.log (rotante, 10MB × 5 backup)
• Nessun TLS, nessun reverse proxy — solo per test locali sulla tua macchina.

Per fermarlo: Ctrl+C, oppure se lanciato in background con nohup:

pkill -f "uvicorn app.main:app"

Docker + Caddy (consigliato, anche per i test con dominio/TLS)

mkdir -p data/db data/keys data/logs   # una tantum, se non già presenti
docker compose up -d --build

• Caddy fa da reverse proxy davanti all'app e gestisce il TLS automaticamente
• App su https://localhost/ (o sul dominio configurato, vedi sotto)
• Pannello admin su https://localhost/admin
• DB, master key cifrata e log persistono in ./data/ sulla root del repo (bind mount, non volumi Docker opachi) — sopravvivono a stop/rebuild del container e sono ispezionabili/backup-abili direttamente

Modalità dev, senza dominio (certificato self-signed)

Non serve fare nulla: lasciando SITE_ADDRESS non impostata, Caddy usa localhost di default. Rilevando che non è un hostname pubblico, genera da solo un certificato dalla sua CA interna — il browser mostrerà un avviso di sicurezza al primo accesso (normale, accettalo o usa curl -k).

Modalità produzione, con dominio reale

SITE_ADDRESS=lottery.tuodominio.it docker compose up -d

Il DNS del dominio deve già puntare all'IP del server, con le porte 80 e 443 raggiungibili da internet. Caddy richiede e rinnova automaticamente un certificato Let's Encrypt reale — nessuna configurazione aggiuntiva.

Comandi utili

docker compose logs -f app     # segui i log dell'app (anche in ./data/logs/app.log)
docker compose ps              # stato dei container
docker compose stop            # ferma senza rimuovere i container
docker compose down            # ferma e rimuove i container (i dati in ./data/ restano)

Nota sul Caddyfile: è montato in sola lettura nel container caddy (bind mount). Modificarlo non basta a farlo ripartire con la nuova configurazione — docker compose up -d --build non ricrea caddy solo perché il contenuto di un file montato è cambiato. Dopo una modifica al Caddyfile serve un passaggio in più:

docker compose restart caddy

(oppure, senza interrompere le connessioni esistenti: docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile).

⚠️ Attenzione: riavvii automatici a metà round

docker-compose.yml imposta restart: unless-stopped sul container dell'app: se crasha, riparte da solo. Questo però non è ancora sicuro in ogni caso — se il crash avviene mentre un round è in stato closing/drawing/paying_out, lo scheduler non lo riprende al riavvio e il round resta bloccato (gap noto, vedi "Known gaps" in CLAUDE.md). Non trattare questo setup come "non supervisionato" finché quel gap non è risolto.