Files

T

davideandClaude Sonnet 5 aae0961c94 Bring docs in sync with recent features (pending balance, SSE, per-player reveal)

CLAUDE.md: bumped the stale test count (54 -> 76), added "Balance display"
and "Real-time updates (SSE)" sections, and rewrote the DRAW section's
frontend-reveal paragraph to describe the actual current behavior (dual
status/result boxes gated by user_played, closes_at-anchored reveal delay,
localStorage persistence, the last-round-result backstop) instead of the
older single-box design. Refined the "no history endpoints" known gap now
that GET /users/me/last-round-result exists (still not general history).

README.md: same test count fix, expanded coverage list.

docs/: fixed a pre-existing broken link in setup.md (admin-guide.md ->
guida-admin.md), added a note in running-the-server.md that editing the
bind-mounted Caddyfile needs an explicit `docker compose restart caddy`
(discovered while adding the SSE Caddy config in a prior change), and
rewrote guida-utente.md's draw/reveal section plus the balance/withdrawal
sections to match what the UI actually does now. guida-admin.md was
reviewed but needed no changes.

app/static/style.css: dropped `.toast.info`, dead since the toast-based
loss notification it styled was replaced by the persistent result box.

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

2026-07-23 11:05:27 +02:00

4.6 KiB

Raw Blame History

Setup

Passaggi da eseguire una tantum per preparare un'istanza di PLM Lottery, prima di poterla avviare (in locale o via Docker). Per come avviarla poi ogni volta, vedi running-the-server.md.

1. Prerequisiti

Python 3.12+ (serve solo per il workflow locale/venv — puoi saltarlo se usi solo Docker)
Docker + Docker Compose (serve solo per il workflow a container)
Un server Electrum raggiungibile per la rete PLM. Il server di bootstrap per lo sviluppo è santantonio.sytes.net:50002 (SSL) — va bene per i test, ma in produzione conviene usarne uno di cui ci si fida o gestirne uno proprio.

2. Creare il file `.env`

Copia .env.example in .env e compila i segreti. Ogni valore sotto viene generato una volta e non cambia più (ruotarlo invalida sessioni/dati cifrati esistenti):

cp .env.example .env

Variabile	Scopo	Come generarla
`XPRV_ENCRYPTION_KEY`	Chiave simmetrica che cifra a riposo la master xprv del server. Perdere questa chiave significa perdere per sempre l'accesso ai fondi di tutti gli utenti.	`python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`
`JWT_SECRET`	Firma i token di sessione degli utenti.	`python -c "import secrets; print(secrets.token_urlsafe(32))"`
`ADMIN_TOKEN`	Token bearer richiesto sugli endpoint admin (header `X-Admin-Token`).	`python -c "import secrets; print(secrets.token_urlsafe(32))"`

Le altre chiavi di .env (DATABASE_URL, ELECTRUM_HOST/PORT/USE_SSL, MASTER_KEY_PATH) hanno default sensati in .env.example. Nota: .env contiene solo segreti e configurazione di infrastruttura — i parametri di business (bet amount, durata round, fee, ecc.) si configurano dal pannello admin dopo l'avvio, non qui — vedi guida-admin.md.

Non committare mai .env. È già escluso da .gitignore.

3. Generare la master key

Il server deriva l'indirizzo di deposito di ogni utente (e l'indirizzo pool) da un'unica master xprv, generata una volta e cifrata a riposo con XPRV_ENCRYPTION_KEY. Questo passaggio va eseguito esattamente una volta per ogni deployment, dopo aver impostato XPRV_ENCRYPTION_KEY in .env:

Locale/venv: PYTHONPATH=. python scripts/generate_master_key.py
Docker: docker compose run --rm app python scripts/generate_master_key.py

Questo scrive un file cifrato (MASTER_KEY_PATH, default ./master.xprv.enc in locale o ./data/keys/master.xprv.enc con Docker). Fai il backup di questo file insieme a XPRV_ENCRYPTION_KEY — uno dei due da solo è inutile, ma perderli entrambi insieme significa perdere i fondi di tutti gli utenti senza possibilità di recupero.

Recuperare o portare una xprv esistente

Due script, entrambi manuali/una tantum, per lo scenario di disaster recovery o per usare una xprv generata altrove (es. offline/air-gapped) invece di farla generare al server:

scripts/decrypt_master_key.py: decifra e stampa a schermo la xprv già presente in MASTER_KEY_PATH (con fallback automatico su ./data/keys/master.xprv.enc se il path di .env non esiste in locale). Chiede conferma esplicita prima di stampare.
scripts/encrypt_master_key.py: cifra una xprv esterna e la scrive in MASTER_KEY_PATH con lo stesso identico schema (Fernet + XPRV_ENCRYPTION_KEY) usato da generate_master_key.py. La xprv va incollata con input nascosto (non appare a schermo). Si rifiuta di sovrascrivere un file esistente a meno di passare --overwrite.

Entrambi vanno eseguiti localmente (o dentro il container via docker compose run --rm app ...), mai esposti da un endpoint API o dal pannello admin: chi ottiene questa xprv ottiene il controllo dei fondi di tutti gli utenti e del pool.

4. Installare le dipendenze (solo workflow locale/venv)

Salta questo passaggio se usi solo Docker — l'immagine installa le proprie dipendenze durante la build.

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

5. Applicare le migrazioni del database

Locale/venv: alembic upgrade head
Docker: le migrazioni vengono eseguite automaticamente all'avvio del container (vedi il CMD del Dockerfile) — nessun passaggio manuale.

6. Impostare l'indirizzo delle fee

Prima che il primo round possa pagare, un admin deve impostare fee_address tramite il pannello admin o l'API — vedi guida-admin.md. I payout si rifiutano di partire finché non è impostato.

A questo punto l'istanza è pronta per essere avviata — continua con running-the-server.md.

4.6 KiB Raw Blame History