davideandClaude Sonnet 5
1941f30b10
decrypt_master_key.py: prints the existing master xprv after an explicit confirmation prompt, for disaster-recovery backups. Falls back to ./data/keys/master.xprv.enc (the docker-compose.yml bind-mount path) when .env's configured MASTER_KEY_PATH doesn't exist locally. encrypt_master_key.py: the reverse direction — takes an externally-generated xprv (e.g. created offline/air-gapped) via a hidden getpass prompt, validates it parses as a private extended key, and encrypts it with the same Fernet scheme generate_master_key.py uses. Refuses to overwrite an existing key file unless --overwrite is passed. Neither script is reachable via any API endpoint or the admin panel, by design — this is the one secret the entire custodial wallet derives from. Documented in docs/setup.md (new "Recuperare o portare una xprv esistente" section) and CLAUDE.md's Commands block. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
101 lines
4.6 KiB
Markdown
101 lines
4.6 KiB
Markdown
# 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](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):
|
|
|
|
```bash
|
|
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](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.
|
|
|
|
```bash
|
|
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](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](running-the-server.md).
|