davideandClaude Opus 5.5
61efbb0e37
The two Mermaid diagrams under flowchart/ described the intended flow but had drifted from the code and carried no link back to it. docs/ now holds the specification instead: 15 Italian documents (flows, architecture, data model, API, security, audit log, operations, decisions and limits, bug history) with 472 numbered requirements, each pointing at the function that implements it and the test that covers it. docs/processo-di-modifica.md defines the ID convention and the spec -> code -> test change workflow, and CLAUDE.md now names docs/ as authoritative. Writing the spec from the code also corrected stale claims in CLAUDE.md (B-41's get_history check, BUGS.md still tracking B-71/B-72, Cache-Control scope, the error contract's bare-string exceptions) and in the operator guides (payouts do retry, only `drawing` fails to resume, rounds do not open without fee_address). The B-70 doc test now pins the prose in docs/scommesse-e-prelievi.md instead of the deleted diagram. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.1 KiB
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 containercaddy(bind mount). Modificarlo non basta a farlo ripartire con la nuova configurazione —docker compose up -d --buildnon ricreacaddysolo perché il contenuto di un file montato è cambiato. Dopo una modifica alCaddyfileserve 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: i
round in closing e paying_out riprendono da soli al riavvio, ma se il
crash avviene mentre un round è in drawing, lo scheduler non lo riprende e
il round resta bloccato (limite noto, vedi
decisioni-e-limiti.md; procedura in
operativita.md). Non trattare questo setup come
"non supervisionato" finché quel limite non è risolto.