# Setup Passaggi da eseguire una tantum per preparare un'istanza di PLM Lottery, prima di poterla avviare. Il server gira sempre in Docker; il venv serve solo a test, migrazioni da generare e script una tantum. Per come avviarla poi ogni volta, vedi [running-the-server.md](running-the-server.md). ## 1. Prerequisiti - Docker + Docker Compose (il server gira solo così) - Python 3.12+ (solo per gli strumenti locali: test, `alembic revision` e gli script delle chiavi) - 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. - **Consigliato in produzione: più di un server.** Tutto passa da questa singola connessione (accredito depositi, invio transazioni, conferme, altezza della catena su cui si basa l'estrazione), quindi un solo server è il principale punto di rottura della piattaforma. Elencane altri in `ELECTRUM_FALLBACK_SERVERS` (vedi sotto): l'app li prova a rotazione, così un server irraggiungibile costa un solo tentativo di riconnessione invece di un disservizio. ## 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): ```bash cp .env.example .env ``` | Variabile | Scopo | Come generarla | |---|---|---| | `XPRV_ENCRYPTION_KEY_FILE` | Percorso del file che contiene la chiave simmetrica che cifra a riposo la master xprv del server (`./secrets/xprv_encryption.key`, cartella `0700`, file `0600`; nel container è montato come secret). **Perdere questa chiave significa perdere per sempre l'accesso ai fondi di tutti gli utenti.** | `mkdir -p secrets && chmod 700 secrets && python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" > secrets/xprv_encryption.key && chmod 600 secrets/xprv_encryption.key` | | `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 chiavi Electrum (`ELECTRUM_HOST`/`PORT`/`USE_SSL`) hanno default sensati in `.env.example`. `DATABASE_URL` e `MASTER_KEY_PATH` non sono elencate lì: hanno un default in `app/config.py`, e dentro il container vengono comunque sovrascritte da `docker-compose.yml` per puntare a `./data/` (elenco completo delle variabili in [architettura.md](architettura.md)). `ENABLE_API_DOCS` (default `false`) controlla Swagger/ReDoc/l'OpenAPI JSON grezzo su `/docs`, `/redoc` e `/openapi.json`: espongono l'intera superficie dell'API, endpoint admin inclusi, quindi restano disattivati a meno di non impostarlo esplicitamente a `true` — utile in locale, da evitare in produzione. `ELECTRUM_FALLBACK_SERVERS` elenca i server di riserva, separati da virgola, nel formato `host:porta` (TLS, il caso normale), `host:porta:notls` oppure `host:porta:pin=` (TLS con il certificato del server fissato). Esempio: ``` ELECTRUM_FALLBACK_SERVERS=nodo2.example.net:50002,nodo3.example.net:50002,nodo4.example.net:50002:pin= ``` Vengono provati a rotazione dopo il primario e servono anche da quorum: ne servono **almeno 2**, altrimenti l'app non parte (`ALLOW_NO_QUORUM=true` lo permette, ma solo in sviluppo). `ELECTRUM_CERT_PIN` fissa allo stesso modo il certificato del primario. Attenzione: un valore scritto male **blocca l'avvio** dell'app — è voluto, meglio accorgersene subito che durante il disservizio in cui il fallback serve davvero. `JWT_SECRET` e la chiave in `XPRV_ENCRYPTION_KEY_FILE` vengono verificati all'avvio: se sono vuoti (o `JWT_SECRET` è più corto di 32 caratteri) il container si rifiuta di partire con un errore esplicito, invece di avviarsi e rompersi al primo login. 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](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 la chiave in `XPRV_ENCRYPTION_KEY_FILE`. Questo passaggio va eseguito esattamente una volta per ogni deployment, dopo aver creato quel file e impostato `XPRV_ENCRYPTION_KEY_FILE` in `.env`: Dal venv: `PYTHONPATH=. python scripts/generate_master_key.py`, con `MASTER_KEY_PATH=./data/keys/master.xprv.enc` in `.env`, così lo script scrive esattamente il file che legge il container. Questo scrive un file cifrato (`MASTER_KEY_PATH`, in Docker `./data/keys/master.xprv.enc`). **Fai il backup di questo file insieme a `secrets/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 gli strumenti locali (venv) Servono per i test e per gli script delle chiavi; il server non ne ha bisogno, perché l'immagine installa le proprie dipendenze (da `requirements.lock`). ```bash python3 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ``` ## 5. Applicare le migrazioni del database Le migrazioni vengono eseguite automaticamente all'avvio del container (vedi il `CMD` del `Dockerfile`) — nessun passaggio manuale, e `alembic upgrade head` non si lancia mai a mano. ## 6. Impostare l'indirizzo delle fee Prima che si possa aprire il primo round, un admin deve impostare `fee_address` tramite il pannello admin o l'API — vedi [guida-admin.md](guida-admin.md). Finché non è impostato **nessun round si apre**, perché il pagamento non si potrebbe costruire. A questo punto l'istanza è pronta per essere avviata — continua con [running-the-server.md](running-the-server.md).