Files

T

davideandClaude Sonnet 5 784f30ddd7 Add docs/ with separate setup, run, user and admin guides

Four standalone Markdown docs instead of growing CLAUDE.md further:
setup.md (one-time secrets/master-key/migrations), running-the-server.md
(local venv vs Docker+Caddy, dev self-signed vs production domain),
guida-utente.md (dashboard: deposit+QR, bet, withdrawal, round timer/
jackpot) and guida-admin.md (the /admin panel and its API equivalent).
Written in Italian per explicit request, unlike the rest of the
repository's English-only docs.

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

2026-07-21 11:22:03 +02:00

2.6 KiB

Raw Blame History

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
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)

⚠️ 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.

2.6 KiB Raw Blame History Unescape Escape