2026-07-21 11:22:03 +02:00
# Setup
2026-11-16 15:06:48 +01:00
## Avvio in locale del nuovo sito (Django)
Servono Docker con Compose e Python 3.12 (solo per i test e per generare la chiave). Nessun nodo né dominio: il sito parte su `https://localhost` con la catena **simulata** ([WEB-07 ](sito-e-app.md )).
```bash
mkdir -p data/db
cp .env.example .env
python3 -c "import secrets; print(secrets.token_urlsafe(64))" # incollare il risultato in DJANGO_SECRET_KEY nel file .env
docker compose up -d --build
```
1. Aprire `https://localhost` : il certificato è autofirmato, l'avviso del browser alla prima visita è atteso.
2. Servizi: `web` (applica le migrazioni), `worker` (apre, chiude ed estrae i round) e `caddy` . Se il worker non gira nessun round si muove: `docker compose logs worker` .
3. Registrarsi su `/registrati/` , caricare un deposito di prova in `/app/portafoglio/` (disponibile solo con la catena simulata) e puntare.
4. Account staff per la console `/ops/` e per `/admin/` :
```bash
docker compose exec web python manage.py createsuperuser
` ``
Un operatore non superutente riceve i permessi dall'admin: ` view_console` per entrare in ` /ops/` e uno per ciascun comando (` pause_after_round`, ` suspend_new_bets`, ` suspend_withdrawals`).
5. Verifica a mano su telefono e desktop: [checklist-verifica-sito.md](checklist-verifica-sito.md). Test automatici: ` python -m pytest`.
6. Spegnere: ` docker compose down` (i dati restano in ` data/db`).
---
> **Nota (migrazione a Django).** Il resto di questa guida descrive il vecchio stack FastAPI, non più nel ` docker-compose.yml`.
2026-11-16 12:00:57 +01:00
2026-07-21 11:22:03 +02:00
Passaggi da eseguire una tantum per preparare un'istanza di PLM Lottery, prima di
2026-10-18 00:54:23 +02:00
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
2026-07-21 11:22:03 +02:00
[running-the-server.md](running-the-server.md).
## 1. Prerequisiti
2026-10-18 00:54:23 +02:00
- Docker + Docker Compose (il server gira solo così)
- Python 3.12+ (solo per gli strumenti locali: test, ` alembic revision` e gli script delle chiavi)
2026-07-21 11:22:03 +02:00
- 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.
2026-07-27 00:34:59 +02:00
- **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.
2026-07-21 11:22:03 +02:00
## 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 |
|---|---|---|
2026-10-18 00:54:23 +02:00
| ` 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` |
2026-07-21 11:22:03 +02:00
| ` 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))"` |
2026-09-28 12:16:01 +02:00
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)).
2026-07-27 00:34:59 +02:00
2026-07-27 15:34:49 +02:00
` 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.
2026-07-27 00:34:59 +02:00
` ELECTRUM_FALLBACK_SERVERS` elenca i server di riserva, separati da virgola, nel
2026-10-14 14:04:35 +02:00
formato ` host:porta` (TLS, il caso normale), ` host:porta:notls` oppure
` host:porta:pin=<sha256>` (TLS con il certificato del server fissato). Esempio:
2026-07-27 00:34:59 +02:00
` ``
2026-10-14 14:04:35 +02:00
ELECTRUM_FALLBACK_SERVERS=nodo2.example.net:50002,nodo3.example.net:50002,nodo4.example.net:50002:pin=<sha256>
2026-07-27 00:34:59 +02:00
` ``
2026-10-14 14:04:35 +02:00
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
2026-07-27 00:34:59 +02:00
disservizio in cui il fallback serve davvero.
2026-10-18 00:54:23 +02:00
` JWT_SECRET` e la chiave in ` XPRV_ENCRYPTION_KEY_FILE` vengono verificati all'avvio: se sono vuoti
2026-07-27 00:34:59 +02:00
(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`
2026-07-21 15:06:51 +02:00
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).
2026-07-21 11:22:03 +02:00
**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
2026-10-18 00:54:23 +02:00
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`:
2026-07-21 11:22:03 +02:00
2026-10-18 00:54:23 +02:00
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.
2026-07-21 11:22:03 +02:00
2026-10-18 00:54:23 +02:00
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
2026-07-21 11:22:03 +02:00
perderli entrambi insieme significa perdere i fondi di tutti gli utenti senza
possibilità di recupero.
2026-07-22 16:20:03 +02:00
### 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.
2026-10-18 00:54:23 +02:00
## 4. Installare gli strumenti locali (venv)
2026-07-21 11:22:03 +02:00
2026-10-18 00:54:23 +02:00
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`).
2026-07-21 11:22:03 +02:00
` ``bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
` ``
## 5. Applicare le migrazioni del database
2026-10-18 00:54:23 +02:00
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.
2026-07-21 11:22:03 +02:00
## 6. Impostare l'indirizzo delle fee
2026-09-28 12:16:01 +02:00
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.
2026-07-21 11:22:03 +02:00
A questo punto l'istanza è pronta per essere avviata — continua con
[running-the-server.md ](running-the-server.md ).