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

# Avviare il server

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

## Locale / venv (sviluppo rapido)

```bash
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](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`:
```bash
pkill -f "uvicorn app.main:app"
```

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

```bash
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

```bash
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

```bash
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ù:
> ```bash
> 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.