Files

T

davideandClaude Sonnet 5 a574db0d93 Align README and running-the-server.md with the Docker-only policy (B-44)

CLAUDE.md declares the server always runs via Docker (dev and prod
alike) with no supported bare-uvicorn workflow, but README's Quick
start and docs/running-the-server.md's "Locale / venv" section still
documented running uvicorn directly — a leftover from before that
policy was adopted. Rewrite both to a single Docker-only path and
update CLAUDE.md's own note about it.

Verified docker compose run --rm app python scripts/generate_master_key.py
against a real build/run to confirm the Quick start's Docker commands
actually work as documented.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-07-27 16:04:24 +02:00

3.0 KiB

Raw Blame History

Avviare il server

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

Il server gira sempre via Docker, in sviluppo e in produzione allo stesso modo — non esiste un modo supportato per lanciare uvicorn direttamente. Il venv locale (.venv/) serve solo per i test, per scrivere le migrazioni Alembic e per gli script una tantum di generazione chiavi (vedi setup.md e la sezione "Commands" di CLAUDE.md).

Docker + Caddy (unico workflow supportato)

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.

3.0 KiB Raw Blame History