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

3.4 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, ROUND_DURATION_SECONDS) hanno default sensati in .env.example — modificali se serve (es. round più corti per i test).

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.

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 admin-guide.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.

3.4 KiB Raw Blame History