davideandClaude Sonnet 5
784f30ddd7
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>
78 lines
3.4 KiB
Markdown
78 lines
3.4 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`, `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.
|
|
|
|
```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).
|