games_app/docs/DEPLOY-VPS.md
2026-11-01 20:02:00 +02:00

1327 lines
53 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Guide de déploiement Tloto sur VPS
Ce guide décrit comment lancer Tloto sur un serveur Linux (VPS) **sans perturber** les autres applications (ports dédiés **9080** / **9443**).
**Démarrage sur base vierge (VPS + local) :** voir la [section 4](#4-démarrage-sur-base-de-données-vierge-vps-et-local).
**Remise à zéro (supprimer / recréer la base) avant tests dépôt/retrait :** voir [section 4.1](#41-remise-à-zéro--supprimer-et-recréer-la-base-avant-tests-réels).
---
## 1. Prérequis sur le VPS
| Outil | Vérification |
|-------|----------------|
| **Docker** | `docker --version` |
| **Docker Compose** | `docker compose version` |
| **Git** | `git --version` |
| **PostgreSQL** | installé sur l’hôte (port 5432) |
| **Node.js** | optionnel (uniquement pour `npm run …` à la racine) |
Si Node n’est pas installé, vous pouvez utiliser directement `docker compose` à la place des scripts `npm run`.
### Ouvrir les ports Prediqo (pare-feu)
```bash
sudo ufw allow 9080/tcp # HTTP (redirection)
sudo ufw allow 9443/tcp # HTTPS
sudo ufw reload
```
### DNS
Le domaine **`prediqo.redirectme.net`** doit pointer vers l’IP du VPS (enregistrement **A**).
---
## 2. Récupérer le projet
```bash
cd ~
git clone https://github.com/japhni/games-project.git games_app
cd games_app
```
*(Adaptez le chemin si vous avez déjà copié le projet.)*
---
## 3. Configurer l’environnement
**Fichier à utiliser sur le VPS : `.env` à la racine du projet** (`games_app/.env`).
```bash
cp .env.example .env
nano .env # ou vim
```
### Variables essentielles à personnaliser
| Variable | Description |
|----------|-------------|
| `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | Compte PostgreSQL sur l’hôte (défaut DB : `games_platform_db`) |
| `DATABASE_URL` / `DATABASE_PASSWORD` | Connexion Docker via `host.docker.internal` (mot de passe encodé si caractères spéciaux) |
| `JWT_SECRET` | Secret JWT (32+ caractères aléatoires) |
| `REDIS_PASSWORD` | Mot de passe Redis (obligatoire) — Redis **non** publié sur l’hôte ; URL conteneurs `redis://:…@redis:6379` |
| `ENCRYPTION_KEY` | 64 caractères hex (32 octets AES-256) — **générer une fois**, backup hors git |
| `PLATFORM_MNEMONIC` | Phrase BIP39 24 mots (générer une fois, garder secrète) |
| `INITIAL_SETUP_TOKEN` | Jeton pour créer le 1er admin (`/setup`) |
| `BREAK_GLASS_TOKEN` | Jeton d’urgence reset 2FA Super Admin (CLI Docker, min 32 car. ; vide = désactivé) |
| `TRON_NODE_URL` | Mainnet : `https://api.trongrid.io` |
| `TRON_API_KEY` | Clé TronGrid (recommandée en prod) |
| `TRON_CONFIRMATIONS` | Ex. `20` |
| `USDT_TRC20_CONTRACT` | Laisser **vide** en mainnet (contrat Tether par défaut en DB) |
| `BSC_RPC_URL` | Mainnet : `https://bsc-dataseed.binance.org` (balances / receipts OK) |
| `BSC_RPC_FALLBACKS` | RPCs pour `eth_getLogs` si le primary renvoie `-32005` (défaut `https://rpc-bsc.48.club`) |
| `BSC_CONFIRMATIONS` | Ex. `15` |
| `BSC_DEPOSIT_INITIAL_LOOKBACK_BLOCKS` | Lookback 1er scan / catch-up balance (défaut `200000` ≈ 7 j) |
| `BSC_DEPOSIT_OVERLAP_LOOKBACK_BLOCKS` | Re-scan chevauchant chaque poll (défaut `5000`) |
| `BSC_UNPAID_LOOKBACK_BLOCKS` | Rattrapage si l’HD a encore de l’USDT (défaut `200000` ≈ 7 j ; plancher avec le lookback initial) |
| `BSCSCAN_API_KEY` / `ETHERSCAN_API_KEY` | Optionnel — Etherscan V2 (BSC peut exiger un plan payant) |
| `BSC_EXPLORER_API_URL` | Optionnel — host tokentx Etherscan-compatible (laisser vide si inutilisé) |
| `USDT_BEP20_CONTRACT` | Laisser **vide** en mainnet (USDT officiel BSC en DB) |
| `ALLOW_WITHDRAWALS` | `false` jusqu’à validation des dépôts (le kill-switch admin Settings prime aussi) |
| `SWEEP_ENABLED` | `false` jusqu’au test cold/sweep ; passer à `true` + cold wallet (voir section trésorerie) |
| `SWEEP_AUTO_EXECUTE` | `false` (défaut) = Submit + Approvals ; `true` = sweep HD→cold automatique après contrôles |
| `SWEEP_AUTO_MAX_AMOUNT_RAW` | Optionnel — au-dessus de ce montant (raw), l’approbation manuelle reste obligatoire |
| `SWEEP_COLD_ALLOWLIST` | Optionnel mais **recommandé** avec auto : adresses cold autorisées (séparées par virgule) |
| `HOT_USDT_MIN_RESERVE_RAW` | Optionnel — plancher USDT laissé sur le hot après Hot→Cold (raw ; `0` = pas de réserve fixe) |
| Approbations (DB) | Règles N-sur-M dans **Options → Règles d’approbation** (pas d’env). Seed défaut = 1 Super Admin + anti auto-approbation. `SWEEP_AUTO_*` reste un fallback / kill-switch pour les sweeps. |
| `APP_PUBLIC_URL` | Ex. HTTP test : `http://prediqo.redirectme.net:9080` · HTTPS : `https://…:9443` |
| `CORS_ORIGINS` | Même origine que le front (schéma + hôte + port) |
| `VITE_API_BASE_URL` | Même URL de base que `APP_PUBLIC_URL` (sans `/api`) — **rebuild** front après changement |
| `VITE_WS_URL` | `ws://…:9080/ws/v1/games/candle-predict` ou `wss://…:9443/…` |
| `CERTBOT_EMAIL` / `CERTBOT_DOMAIN1` | Let’s Encrypt (parcours HTTPS) |
| `SMTP_*` / `EMAIL_FROM` | E-mails (vérification, reset mot de passe) |
### Générer ou régénérer les secrets
Exécutez ces commandes sur le VPS (ou en local, puis collez **uniquement** dans `.env` — ne les partagez jamais). Chaque secret doit être **unique** et différent des exemples du dépôt.
#### `ENCRYPTION_KEY` (64 caractères hex)
```bash
# Linux / macOS / Git Bash (OpenSSL)
openssl rand -hex 32
# Ou avec Node (partout où node est installé)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
Collez le résultat dans `.env` :
```env
ENCRYPTION_KEY=…64 hex chars…
```
> Si des hot wallets existent déjà en base, ne changez pas `ENCRYPTION_KEY` sans suivre la rotation documentée (`deploy/ENCRYPTION_KEY_ROTATION.md`). Sinon les clés chiffrées deviennent illisibles.
#### `PLATFORM_MNEMONIC` (24 mots BIP39)
Depuis le dossier `backend` du dépôt (où le paquet `bip39` est installé) :
```bash
cd /chemin/vers/games_app/backend
node -e "console.log(require('bip39').generateMnemonic(256))"
```
Collez la **ligne entière** (24 mots séparés par des espaces) :
```env
PLATFORM_MNEMONIC=word1 word2 word3 … word24
```
- Pas de virgules, pas de retours à la ligne, pas de guillemets.
- Ne réutilisez **jamais** un mnémonique de testnet / Shasta en mainnet.
- Changer le mnémonique = nouvelles adresses de dépôt et nouveau hot wallet. Les fonds déjà envoyés aux anciennes adresses ne sont récupérables qu’avec l’**ancien** mnémonique.
Après un premier mnémonique + `ENCRYPTION_KEY` valides (stack déjà démarrée une fois) :
**Sur le VPS (Docker)** — depuis la racine du dépôt (là où se trouve `docker-compose.yml` et `.env`) :
```bash
cd ~/projects_repository/games-project # adaptez le chemin
sudo docker compose run --rm --no-deps backend node dist/scripts/seedHotWallets.js
```
Ne lancez **pas** `npm run seed-hot-wallets` sur l’hôte du VPS : ce script utilise `ts-node`, absent en prod. Utilisez le JS compilé dans le conteneur `backend` (comme pour les migrations).
**En local (dev, sans Docker)** :
```bash
cd backend
npm install # si besoin (inclut ts-node)
npm run seed-hot-wallets
```
Une seule fois suffit : si un hot wallet existe déjà pour un réseau, le script affiche `Skipping` pour ce type. Le seed crée **deux** hot wallets : `USDT_TRC20` (TRON, index `1000000`) et `USDT_BEP20` (BSC, index `1000001`).
- Hot **TRON** : financer en **TRX** (gas) + USDT TRC20 — float plateforme pour **tous** les retraits TRC20 (même si le user a déposé en BEP20).
- Hot **BSC** : financer en **BNB** (gas) + USDT BEP20 — float pour **tous** les retraits BEP20.
- Dimensionnez les deux hots comme **trésorerie de payout** (gains inclus), pas seulement comme miroir des dépôts du même réseau.
#### Rotation des adresses de dépôt (après changement de `PLATFORM_MNEMONIC`)
Si des utilisateurs ont déjà une adresse créée avec un **ancien** mnémonique, l’app continue d’afficher cette adresse (`getOrCreateDepositAddress` ne la régénère pas). Pour forcer de **nouvelles** adresses dérivées du mnémonique **actuel** :
> **Danger :** tout USDT encore sur les **anciennes** adresses on-chain devient incontrôlable sans l’ancien mnémonique. À n’utiliser que si ces adresses sont vides (ou après sweep avec l’ancien mnémonique).
```bash
cd ~/projects_repository/game-project
# Tous les users qui ont déjà une adresse (TRC20 + BEP20)
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/rotateDepositAddresses.js \
--confirm=ROTATE_DEPOSIT_ADDRESSES \
--scope=existing \
--wallet-type=ALL
# Ou un seul compte de test
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/rotateDepositAddresses.js \
--confirm=ROTATE_DEPOSIT_ADDRESSES \
--email=test@example.com \
--wallet-type=ALL
```
Équivalent : `npm run phase-b:rotate-deposit-addresses -- --confirm=ROTATE_DEPOSIT_ADDRESSES --scope=existing --wallet-type=ALL`
Le script ne touche **pas** aux hot wallets ni aux soldes ledger. Ensuite, ouvrir **Dépôt** dans l’app et n’envoyer de l’USDT réel **que** vers la nouvelle adresse affichée (bon réseau : `T…` = TRC20, `0x…` = BEP20).
Pour **vérifier** que chaque adresse `user_wallets` correspond au mnémonique actuel :
```bash
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/verifyDepositAddresses.js
# optionnel : --wallet-type=USDT_BEP20
```
`--scope=existing` ne traite que les lignes **`user_wallets`** d’utilisateurs non supprimés. Les hot/cold wallets et les adresses dans `transactions` ne sont pas des adresses de dépôt user.
#### `JWT_SECRET` et `INITIAL_SETUP_TOKEN`
Deux valeurs **différentes**, chacune ≥ 32 caractères aléatoires :
```bash
# JWT_SECRET
node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
# INITIAL_SETUP_TOKEN (relancer pour une autre valeur)
node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
```
```env
JWT_SECRET=…
INITIAL_SETUP_TOKEN=…
```
`INITIAL_SETUP_TOKEN` ne sert qu’à créer le premier administrateur sur `/setup`. Une fois un admin créé, il n’est plus nécessaire pour le quotidien ; vous pouvez le régénérer ou le laisser.
#### `BREAK_GLASS_TOKEN` (récupération d’urgence 2FA Super Admin)
Distinct de `JWT_SECRET` et `INITIAL_SETUP_TOKEN`. Générez une valeur ≥ 32 caractères :
```bash
node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
```
```env
BREAK_GLASS_TOKEN=…
```
Laissez vide pour **désactiver** le break-glass jusqu’à ce que vous en ayez besoin. Voir [section Break-glass 2FA](#break-glass--reset-durgence-du-2fa-super-admin).
#### Mot de passe PostgreSQL (`DATABASE_PASSWORD` / `POSTGRES_PASSWORD`)
Choisissez un mot de passe long et aléatoire. Dans `DATABASE_URL`, encodez les caractères spéciaux :
| Caractère | Dans l’URL |
|-----------|------------|
| `@` | `%40` |
| `!` | `%21` |
| `#` | `%23` |
| `%` | `%25` |
| `/` | `%2F` |
| `:` | `%3A` |
Exemple si le mot de passe réel est `Japhni82@@!` :
```env
DATABASE_PASSWORD=Japhni82@@!
POSTGRES_PASSWORD=Japhni82@@!
DATABASE_URL=postgresql://postgres:Japhni82%40%40%21@host.docker.internal:5432/games_platform_db
```
Le backend préfère `DATABASE_PASSWORD` pour la connexion ; l’URL encodée évite les erreurs avec d’autres outils. **Ne** mettez **pas** le littéral `DATABASE_PASSWORD` dans l’URL : ce n’est pas interpolé.
#### `TRON_API_KEY`
1. Compte sur [TronGrid](https://www.trongrid.io/) (e-mail + confirmation).
2. À l’activation, **Skip** le lien wallet (TronLink n’est pas requis pour Prediqo).
3. Dashboard → Create API Key → coller dans `.env` :
```env
TRON_API_KEY=…
```
Après toute modification de secrets dans `.env`, redémarrez la stack (`sudo npm run phase-b:up` ou équivalent). Rebuild `prediqo-web` uniquement si vous changez les `VITE_*`.
### Configuration SMTP (Microsoft 365 / GoDaddy — recommandé pour `tloto.net`)
Objectif : les destinataires voient **`info@tloto.net`** comme expéditeur, en s’authentifiant avec la boîte **`admin@tloto.net`** (l’alias ne nécessite pas d’abonnement supplémentaire).
**Prérequis GoDaddy / Microsoft 365 (à vérifier avant de changer le VPS) :**
1. `info@tloto.net` est bien un **alias / adresse proxy** de la boîte `admin@tloto.net` (pas une boîte séparée non liée).
2. L’envoi « **Send As** » / envoi depuis l’alias est autorisé pour ce compte (souvent automatique pour les alias M365 ; sinon Admin center → Users → Mail → Email aliases / Send as).
3. SMTP client authentifié activé pour la boîte (standard M365 : `smtp.office365.com:587` STARTTLS).
Dans le **`.env` à la racine du VPS** (secrets hors Git) :
```env
EMAIL_TRANSPORT=smtp
SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=admin@tloto.net
SMTP_PASS=mot-de-passe-de-la-boite-admin
EMAIL_FROM="Tloto <info@tloto.net>"
EMAIL_REPLY_TO=info@tloto.net
APP_PUBLIC_URL=https://tloto.net
RESET_PASSWORD_PATH=/reset-password
VERIFY_EMAIL_PATH=/verify-email
```
- `SMTP_USER` / `SMTP_PASS` = authentification (boîte principale).
- `EMAIL_FROM` = en-tête **From** visible (alias).
- `EMAIL_REPLY_TO` = réponses vers l’alias (sinon dérivé de `EMAIL_FROM`).
**Tester (après `git pull` + recreate backend pour injecter les env) :**
```bash
sudo docker compose up -d --force-recreate backend
sudo npm run phase-b:verify-smtp
# Envoi réel de test (remplacer l’adresse) :
sudo docker compose run --rm --no-deps -e SMTP_TEST_TO=votre@email.com backend node dist/scripts/verifySmtp.js
```
Contrôler dans la boîte de réception : From = `info@tloto.net`, Reply-To = `info@tloto.net`.
Si erreur du type `SendAsDenied` / `550 5.7.60` : l’alias n’a pas le droit d’envoyer — corriger dans M365/GoDaddy avant de retenter.
#### Erreur `535 5.7.139 … SmtpClientAuthentication is disabled for the Tenant`
La config Tloto est correcte (`EMAIL_FROM` / `SMTP_USER`), mais **Microsoft 365 bloque SMTP AUTH** sur le tenant (souvent désactivé par défaut).
Activer SMTP AUTH (une des voies) :
1. **Pour la boîte `admin@tloto.net` (recommandé)**
- [Microsoft 365 admin center](https://admin.microsoft.com) → **Users** → **Active users** → `admin@tloto.net`
- **Mail** → **Manage email apps** / **Email apps**
- Cocher **Authenticated SMTP** → Save
Ou PowerShell Exchange Online :
```powershell
Set-CASMailbox -Identity admin@tloto.net -SmtpClientAuthenticationDisabled $false
```
2. **Au niveau organisation** (si la case boîte est grisée)
- Admin center → **Settings** → **Org settings** → **Modern authentication** / **Mail**
- Ou : [https://aka.ms/smtp_auth_disabled](https://aka.ms/smtp_auth_disabled)
- Autoriser SMTP AUTH pour le tenant, puis réactiver sur la boîte.
3. Chez **GoDaddy** : Email & Office → Admin / Microsoft 365 → gérer l’utilisateur `admin@` → options de messagerie / SMTP authentifié (libellés varient).
Attendre 1–15 minutes, puis :
```bash
sudo npm run phase-b:verify-smtp
sudo docker compose run --rm --no-deps -e SMTP_TEST_TO=votre@email.com backend node dist/scripts/verifySmtp.js
```
Si MFA est obligatoire sur le compte : créer un **mot de passe d’application** Microsoft et le mettre dans `SMTP_PASS` (pas le mot de passe de connexion web).
> **Tloto n’utilise plus Gmail** comme expéditeur. Uniquement Microsoft 365 (`admin@` / alias `info@`).
> **Ne pas committer `.env`** — il est ignoré par Git.
### Base de données PostgreSQL (sur l’hôte) — **obligatoire avant le 1er démarrage**
Utilisez **le même nom** que `POSTGRES_DB` dans `.env` (recommandé : `games_platform_db`).
Créez la base si nécessaire :
```bash
sudo -u postgres psql -c "CREATE DATABASE games_platform_db;"
```
Si votre utilisateur PostgreSQL n’est pas `postgres`, adaptez :
```bash
sudo -u postgres psql -c "CREATE USER votre_user WITH PASSWORD 'votre_mot_de_passe';"
sudo -u postgres psql -c "CREATE DATABASE games_platform_db OWNER votre_user;"
```
Vérifiez la connexion :
```bash
psql -U postgres -h localhost -d games_platform_db -c "SELECT 1;"
```
Les identifiants doivent correspondre à `POSTGRES_USER`, `POSTGRES_PASSWORD` et `POSTGRES_DB` dans `.env`.
**URL base de données pour Docker (important) :**
```env
POSTGRES_DB=games_platform_db
POSTGRES_USER=postgres
POSTGRES_PASSWORD=votre_mot_de_passe
DATABASE_PASSWORD=votre_mot_de_passe
# Les conteneurs ne peuvent PAS utiliser localhost — utiliser host.docker.internal :
DATABASE_URL=postgresql://postgres:votre_mot_de_passe@host.docker.internal:5432/games_platform_db
```
`psql` sur l’hôte utilise `localhost` ; les **conteneurs** utilisent `host.docker.internal`.
### PostgreSQL : autoriser les connexions depuis Docker (Linux)
Si `psql` fonctionne sur l’hôte mais le backend Docker redémarre en boucle (`password authentication failed` ou `ECONNREFUSED`), PostgreSQL refuse souvent les connexions venant du réseau Docker.
Éditez `pg_hba.conf` (ex. `/etc/postgresql/16/main/pg_hba.conf`) et ajoutez **avant** les règles « reject » :
```
host all all 172.16.0.0/12 scram-sha-256
```
Dans `postgresql.conf`, vérifiez :
```
listen_addresses = 'localhost'
```
(suffit en général avec `host.docker.internal` + port forwarding Docker)
Puis :
```bash
sudo systemctl reload postgresql
```
**Test depuis un conteneur :**
```bash
sudo docker compose run --rm --no-deps backend node -e "
const { Client } = require('pg');
const c = new Client({ connectionString: process.env.DATABASE_URL });
c.connect().then(() => { console.log('DB OK'); return c.end(); }).catch(e => { console.error(e.message); process.exit(1); });
"
```
Les conteneurs Docker se connectent via `host.docker.internal` (configuré dans `docker-compose.yml`). Au démarrage, le backend exécute les **migrations** automatiquement.
**Erreur typique si cette étape est oubliée :**
```
error: database "games_platform_db" does not exist
```
→ le backend et nginx redémarrent en boucle, le port **9080** ne répond pas.
---
## 4. Démarrage sur base de données vierge (VPS et local)
Cette section regroupe les commandes lorsque PostgreSQL est **vide** (base créée, **sans schéma**) ou après une [remise à zéro](#41-remise-à-zéro--supprimer-et-recréer-la-base-avant-tests-réels).
### Checklist configuration initiale (ordre recommandé)
| # | Étape | Détail |
|---|--------|--------|
| 1 | `.env` complet | Secrets générés **une fois** + backup hors git · TRON + BSC mainnet · URLs HTTP ou HTTPS cohérentes · `ALLOW_WITHDRAWALS=false` |
| 2 | Base Postgres | Créée (ou DROP + CREATE) avec le nom `POSTGRES_DB` |
| 3 | Migrations + stack | `phase-b:init` (HTTP) ou `phase-b:init:https` |
| 4 | Santé | `curl` `/health` → `assets` inclut `USDT_TRC20` + `USDT_BEP20` · `/setup/status` → `needsSetup: true` |
| 5 | Premier Super Admin | Page `/setup` + `INITIAL_SETUP_TOKEN` |
| 6 | 2FA + recovery codes | Profil → activer 2FA · sauvegarder les codes hors ligne |
| 7 | (Recommandé) 2ᵉ admin | Ne pas dépendre d’un seul Super Admin |
| 8 | Hot wallets | `seedHotWallets.js` **une fois** · noter adresses TRON **et** BSC |
| 9 | Vérifier HD | `verifyDepositAddresses.js` → 0 mismatch (les deux réseaux) |
| 10 | Prêt dépôt test | **Priorité BEP20** (Binance → BSC) · retraits encore **off** · TRC20 optionnel ensuite |
> **Ne changez plus** `ENCRYPTION_KEY` ni `PLATFORM_MNEMONIC` après l’étape 8 sans procédure de rotation (sinon PII / hot wallet / adresses orphelines).
### Test argent réel — ordre BEP20 d’abord
1. Admin → Settings → **USDT networks** : activer dépôt (et plus tard retrait) **BEP20** ; TRC20 selon besoin.
2. Financer le hot BSC avec **BNB** + USDT BEP20 (float retraits). Pour les retraits cross-réseau TRC20, financer aussi le hot TRON (TRX + USDT).
3. User test → Receive → réseau **BSC (BEP20)** → copier l’adresse `0x…`.
4. Depuis Binance (ou wallet) : retirer USDT en réseau **BEP20 / BSC** uniquement (pas TRC20).
5. Attendre confirmations → **solde USDT unifié** crédité (Candle Predict utilise ce solde).
6. Micro-retrait : activer kill-switch global + flag withdraw BEP20 → retirer vers une adresse BSC (plafond = solde ledger ; le hot doit avoir assez d’USDT + BNB).
7. (Optionnel) activer withdraw TRC20 → même solde retirable en TRC20 si le hot TRON a assez d’USDT + TRX (indépendant du réseau de dépôt).
> **Ledger unifié + float hot :** dépôts TRC20 et BEP20 alimentent le même solde jouable (`USDT_TRC20` en DB, 6 décimales). Le réseau de retrait n’a **pas** à correspondre au dépôt ; l’API refuse un retrait si le hot du rail choisi n’a pas assez d’USDT ou de gas (`HOT_WALLET_INSUFFICIENT_LIQUIDITY`). L’inventaire par réseau reste un compteur ops (dépôts), pas un plafond joueur.
#### Dépôt BEP20 confirmé on-chain mais pas crédité
> **Ordre réel :** détection → **crédit Ledger / Main Wallet** → (si `SWEEP_ENABLED`) enqueue sweep HD→cold.
> Le sweep ne crédite **pas** le joueur. Tant que le ledger n’est pas crédité, `SWEEP_ENABLED=true` ne change rien.
1. Vérifier sur BscScan que l’USDT est bien sur l’adresse Receive BEP20 du user (contrat `0x55d39832…7955`).
2. Admin → Settings → dépôt **BEP20** activé.
3. Logs `crypto_wallet_api` : si vous voyez `eth_getLogs` / `limit exceeded` (-32005) en boucle, le dataseed Binance rate-limit — le backend doit basculer sur `BSC_RPC_FALLBACKS` (rebuild requis). Cherchez ensuite `[bsc] eth_getLogs succeeded via fallback` puis `[deposit] credited USDT_BEP20`.
4. Après déploiement avec fallbacks : le monitor crédite tout seul (getLogs fallback + receipt). Le script n’est qu’un rattrapage exceptionnel :
```bash
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/creditBscDepositByTx.js \
--tx=0xVOTRE_TX_HASH
```
5. Logs backend : `[deposit] USDT_BEP20` / `[deposit] credited USDT_BEP20` / éventuellement `recovered unpaid via tx=`.
### Test trésorerie — Cold wallet + Sweep + Cold→Hot (BEP20)
Objectif : valider le circuit **Dépôt user → adresse HD dépôt → Sweep → Cold → alimentation Hot → Retrait**.
#### Prérequis
1. Hot BSC déjà seedé et financé en **BNB** (gas pour sweeps + retraits).
2. Créer une adresse **cold** BEP20 sous votre contrôle (MetaMask / hardware / cold storage) — **distincte** du hot et des adresses user.
3. Dans le `.env` VPS :
```env
SWEEP_ENABLED=true
# Optionnel — sweep sans Approvals (garder false si vous voulez une revue humaine) :
# SWEEP_AUTO_EXECUTE=true
# SWEEP_COLD_ALLOWLIST=0xVotreColdBep20
# SWEEP_AUTO_MAX_AMOUNT_RAW=100000000000000000000
# optionnel : min on-chain (défaut 1000000 — largement sous 1 USDT BEP20 à 18 déc.)
# SWEEP_MIN_AMOUNT_RAW=1000000
# top-up BNB vers l’adresse de dépôt avant transfer USDT (défaut 0.001 BNB)
# SWEEP_BSC_GAS_TOPUP_WEI=1000000000000000
```
> **Approbation vs auto :** par défaut, « Submit sweeps for approval » + Approvals est un **contrôle ops** (revoir destination / montant). Ce n’est pas ce qui protège contre une compromission totale du serveur (`PLATFORM_MNEMONIC` suffit déjà à signer). Avec `SWEEP_AUTO_EXECUTE=true`, le job exécute les sweeps éligibles après vérif cold actif = allowlist, solde HD ≥ montant, min amount. Les montants au-dessus de `SWEEP_AUTO_MAX_AMOUNT_RAW` restent manuels.
4. Recréer le backend pour injecter les vars (`docker-compose` les passe désormais) :
```bash
sudo docker compose --profile http up -d --force-recreate backend
# ou profil https-dns selon votre stack
```
5. Admin → **Treasury** : chip **Sweeps enabled**. Pour **USDT (BEP20)** : coller l’adresse cold → **Save cold**.
#### A. Sweep dépôt → Cold
| Étape | Action | Vérifier |
|-------|--------|----------|
| 1 | Micro-dépôt BEP20 vers l’adresse Receive user (ou réutiliser un dépôt déjà on-chain sur l’HD) | Ledger crédité ; solde USDT encore sur l’**adresse de dépôt** (pas le hot) |
| 2 | Si le dépôt a été crédité **avant** cold/`SWEEP_ENABLED` : enqueue manuel | Script ci-dessous |
| 3 | Treasury → table Deposit sweeps : statut `pending` | Ligne vers l’adresse cold |
| 4 | **Submit sweeps for approval** (ou attendre ~15 min le job auto) | Message : lot soumis |
| 5 | **Approvals** → approuver `sweep_batch` (super_admin) | Backend : gas BNB hot→dépôt si besoin, puis USDT dépôt→cold |
| 6 | BscScan cold + Treasury | Solde USDT cold ↑ ; sweep `completed` + tx hash ; logs `[sweep]` |
Enqueue d’un dépôt déjà crédité :
```bash
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/enqueueSweepForDepositTx.js \
--tx=0xVOTRE_TX_HASH_DEPOT
```
Échecs typiques : pas de cold BEP20, `SWEEP_ENABLED=false` (chip Sweeps disabled), hot BNB insuffisant pour le top-up gas, sweep `failed` → message d’erreur dans Treasury.
> Le sweep **ne touche pas** le ledger utilisateur (déjà crédité au dépôt). Il déplace uniquement l’USDT on-chain de l’HD vers le cold.
#### B. Cold → Hot (float retraits)
Le transfert on-chain est **manuel** (clé cold hors plateforme) ; Prediqo enregistre la demande + la confirmation.
> **Important :** le cold doit être une adresse **externe** (MetaMask / hardware), **pas** une adresse Receive d’un user Prediqo (HD). Sinon vous ne pourrez pas signer le Cold → Hot.
1. Treasury → **Hot ↔ Cold USDT** : route **Cold → Hot**, réseau **USDT (BEP20)**, montant en **USDT** (ex. `2`) → **Request funding** → Approvals.
2. Après approbation : transferrer manuellement USDT BEP20 **cold → hot** (adresse hot affichée / Copier).
3. Treasury → **Confirm tx** avec le hash BscScan.
4. Vérifier le solde USDT hot on-chain (Treasury / explorateur).
#### B2. Hot → Cold USDT (excédent hot → cold)
Après Approvals, la **plateforme** signe depuis le hot (pas MetaMask). Destination = cold **actif** en base uniquement.
1. Treasury → **Hot ↔ Cold USDT** : route **Hot → Cold**, réseau, montant (ou **Max**) → **Request hot → cold**.
2. Approvals → Super Admin approuve `treasury_hot_to_cold` → broadcast on-chain automatique.
3. Contrôles : solde USDT hot, gas natif ≥ min retrait, plancher optionnel `HOT_USDT_MIN_RESERVE_RAW` (défaut `0` = pas de réserve USDT fixe ; max envoyable = solde − réserve).
```bash
# Exemple .env / docker-compose (défaut)
HOT_USDT_MIN_RESERVE_RAW=0
# Ex. BEP20 : garder ~10 USDT sur le hot → 10000000000000000000
```
Différence vs gas Hot→Cold : ici c’est de l’**USDT** ; le gas Hot→Cold reste la carte « Gas transfer » (BNB / TRX).
### Règles d’approbation (N-sur-M)
Après migration DB, les tables `approval_policies` / `fund_operation_votes` sont créées et seedées (1× Super Admin, `forbid_self_approve`).
- **UI** : Options → **Règles d’approbation** (`/admin/approval-policies`). Les changements passent par Approvals (`approval_policy_change`) — pas de save silencieux.
- **Retraits** : au-dessus de `large_withdrawal_threshold_usd` (Settings) → file Approvals `user_withdrawal` ; en dessous → broadcast immédiat (comportement historique).
- **Sweeps** : `SWEEP_AUTO_EXECUTE` / `SWEEP_AUTO_MAX_AMOUNT_RAW` continuent de fonctionner. Vous pouvez aussi ajouter une policy DB `sweep_batch` en `auto_execute` avec `amount_max_raw` ; la policy DB s’applique aux demandes créées via `createFundRequest`.
##### Récupérer des USDT bloqués sur une « fausse » cold (adresse HD user)
Si une adresse Receive Prediqo a été enregistrée comme cold par erreur :
```bash
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/recoverHdUsdtToHot.js \
--from=0xADRESSE_HD_FAUSSE_COLD \
--confirm=YES
```
Optionnel : `--amount=6` (USDT humain ; défaut = solde on-chain entier).
Le script dérive la clé HD, top-up BNB depuis le hot si besoin, envoie l’USDT vers le hot actif, puis affiche le `transferTx`.
Si du **BNB** (gas de top-up) reste sur l’ancienne HD après le transfert USDT :
```bash
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/recoverHdUsdtToHot.js \
--from=0xADRESSE_HD_FAUSSE_COLD \
--native-only=YES \
--confirm=YES
```
Ensuite : **Save cold** avec une vraie adresse MetaMask, puis reprendre le parcours Cold → Hot normal.
#### C. Cycle complet
1. Dépôt user BEP20 → crédit ledger.
2. Sweep approuvé → USDT sur cold.
3. Cold→Hot confirmé → float hot reconstitué.
4. Retrait user BEP20 (kill-switch + rail withdraw on) → débit ledger + tx depuis le **hot**.
Checklist traçabilité : transaction dépôt, ligne `deposit_sweeps`, demande Approvals `sweep_batch` / `treasury_cold_to_hot`, funding confirmé, retrait + audit logs.
### Prérequis communs
| Étape | Détail |
|-------|--------|
| Base PostgreSQL | Base vide créée (`games_platform_db` selon `.env`) |
| Jeton setup | `INITIAL_SETUP_TOKEN` — min. 16 caractères, **32+ aléatoires recommandés** |
| Fichier env | VPS → `.env` · Local Docker → `.env.docker` |
| Connexion Docker → Postgres | `DATABASE_URL` avec **`host.docker.internal`**, pas `localhost` |
Vérifier que l’API répond avant `/setup` :
```bash
curl -s http://127.0.0.1:9080/api/v1/setup/status
# attendu : {"needsSetup":true,"setupEnabled":true}
curl -s http://127.0.0.1:9080/health
# attendu : "assets":["USDT_TRC20","USDT_BEP20"], "withdrawalsEnabled": false (ou selon Settings)
```
### 4.1 Remise à zéro — supprimer et recréer la base (avant tests réels)
Utilisez cette procédure pour repartir **depuis zéro** (users / ledger / hot wallet DB effacés).
**Attention :** toute donnée applicative dans Postgres est perdue. Les USDT **déjà** envoyés on-chain vers d’anciennes adresses ne sont **pas** effacés par un DROP DB — ne le faites que si ces adresses sont vides ou si vous acceptez de les abandonner.
```bash
cd ~/projects_repository/games-project # adaptez le chemin
# 1) Arrêter la stack Prediqo (ne touche pas aux autres apps du VPS)
sudo docker compose --profile http down
# si vous étiez en HTTPS : sudo docker compose --profile https-dns down
# 2) Couper les sessions Postgres sur la base, puis DROP + CREATE
# Remplacez games_platform_db si POSTGRES_DB est différent dans .env
sudo -u postgres psql -v ON_ERROR_STOP=1 <<'SQL'
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE datname = 'games_platform_db' AND pid <> pg_backend_pid();
DROP DATABASE IF EXISTS games_platform_db;
CREATE DATABASE games_platform_db OWNER postgres;
SQL
# 3) (Recommandé avant argent réel) régénérer ENCRYPTION_KEY, PLATFORM_MNEMONIC,
# JWT_SECRET, INITIAL_SETUP_TOKEN — une seule fois — et les sauvegarder hors git.
# Ne pas réutiliser un mnémonique / ENCRYPTION_KEY déjà exposés dans un chat.
# 4) Vérifier .env : TRON + BSC mainnet, TRON_API_KEY, BSC_RPC_URL, ALLOW_WITHDRAWALS=false,
# APP_PUBLIC_URL / VITE_* / CORS_ORIGINS alignés (http://…:9080 ou https://…:9443)
# 5) Migrations + démarrage HTTP
sudo npm run phase-b:init
# sans Node sur le VPS :
# sudo docker compose run --rm --no-deps --build backend node dist/db/migrate.js
# sudo docker compose --profile http up -d --build
# 6) Setup navigateur → /setup → premier Super Admin → login → 2FA + recovery codes
# 7) Hot wallets TRON + BSC (une fois)
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/seedHotWallets.js
# 8) Vérifier les adresses HD (les deux réseaux)
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/verifyDepositAddresses.js
```
Ensuite seulement : créer un user de test → Dépôt → micro USDT **BEP20** (priorité) → (plus tard) financer les hots puis activer les retraits dans Admin Settings (réseau + kill-switch global).
### Sur le VPS
À la racine du projet (`games_app/`) :
```bash
cp .env.example .env
# Éditer .env : PostgreSQL, secrets, INITIAL_SETUP_TOKEN, URLs publiques
```
**Premier déploiement (base vierge) — migrations + stack :**
```bash
# HTTP (test rapide)
npm run phase-b:init
# HTTPS (production — certificat DNS requis une fois avant)
npm run ssl:dns-init
npm run phase-b:init:https
```
Équivalents Docker directs (sans Node.js sur le VPS) :
```bash
# Migrations seules
docker compose run --rm --no-deps --build backend node dist/db/migrate.js
# Puis démarrage
docker compose --profile http up -d --build # HTTP
docker compose --profile https-dns up -d --build # HTTPS
```
**Démarrages suivants** (base déjà migrée, pas de changement de schéma) :
```bash
npm run phase-b:up # HTTP
npm run phase-b:up:https # HTTPS
```
**Configuration initiale (navigateur) :**
| Mode | URL setup |
|------|-----------|
| HTTP | `http://prediqo.redirectme.net:9080/setup` |
| HTTPS | `https://prediqo.redirectme.net:9443/setup` |
1. Saisir le **`INITIAL_SETUP_TOKEN`** (valeur de `.env` sur le serveur).
2. Créer le premier administrateur **ou** promouvoir un compte existant.
3. Un **code de parrainage racine** est généré automatiquement pour ce super admin ; les inscriptions sans code y seront rattachées.
4. Se connecter sur **`/login`**.
### En local — Docker (même stack que le VPS)
Fichier d’environnement dédié : **`.env.docker`** (non versionné).
```bash
cp .env.docker.example .env.docker
# Éditer .env.docker : POSTGRES_PASSWORD, JWT_SECRET, ENCRYPTION_KEY,
# PLATFORM_MNEMONIC, INITIAL_SETUP_TOKEN
# Garder NODE_ENV=development + Shasta (production + testnet = crash au boot).
# Créer la base vide sur PostgreSQL local, ex. games_platform_db
```
**Premier démarrage (base vierge) :**
```bash
npm run docker:local:init
```
Équivalent :
```bash
docker compose --env-file .env.docker run --rm --no-deps --build backend node dist/db/migrate.js
docker compose --env-file .env.docker --profile http up -d --build
```
**Configuration initiale :** [http://localhost:9080/setup](http://localhost:9080/setup)
**Démarrages suivants :**
```bash
npm run docker:local:up
```
**Migrations seules** (après `git pull` avec changement de schéma) :
```bash
npm run docker:local:migrate
# ou : npm run db:migrate (utilise .env racine, pas .env.docker)
```
Autres commandes locales utiles : `npm run docker:local:status` · `docker:local:logs` · `docker:local:down`
### En local — sans Docker (backend Node + Postgres sur la machine)
Utile pour le développement backend pur :
```bash
cd backend
cp .env.example .env
# DATABASE_URL=postgresql://user:pass@localhost:5432/crypto_wallet
npm run migrate
npm run dev
```
Frontend en dev (autre terminal) :
```bash
cd prediqo_web
cp .env.example .env
# VITE_API_BASE_URL=http://localhost:4000
npm install
npm run dev
```
Page setup : **`http://localhost:5173/setup`** (ou le port Vite affiché), l’API étant sur le port configuré dans `VITE_API_BASE_URL`.
### Table récapitulative
| Contexte | Fichier env | 1er démarrage (base vierge) | Page setup |
|----------|-------------|-----------------------------|------------|
| **VPS HTTP** | `.env` | `npm run phase-b:init` | `:9080/setup` |
| **VPS HTTPS** | `.env` | `npm run phase-b:init:https` | `:9443/setup` |
| **Local Docker** | `.env.docker` | `npm run docker:local:init` | `http://localhost:9080/setup` |
| **Local sans Docker** | `backend/.env` | `cd backend && npm run migrate` puis `npm run dev` | frontend dev + `/setup` |
| Action | VPS | Local Docker |
|--------|-----|--------------|
| Migrations seules | `npm run db:migrate` | `npm run docker:local:migrate` |
| État conteneurs | `npm run phase-b:status` | `npm run docker:local:status` |
| Logs | `npm run phase-b:logs` | `npm run docker:local:logs` |
---
## 5. Lancer l’application
Deux parcours : **HTTP rapide** (test) ou **HTTPS recommandé** (production).
### Parcours A — HTTP (test rapide)
**Important :** les URLs `VITE_*` et `APP_PUBLIC_URL` doivent utiliser **http** et le port **9080** (pas https/9443).
```env
APP_PUBLIC_URL=http://prediqo.redirectme.net:9080
VITE_API_BASE_URL=http://prediqo.redirectme.net:9080
VITE_WS_URL=ws://prediqo.redirectme.net:9080/ws/v1/games/candle-predict
```
```bash
# 1er déploiement (migrations + démarrage en une commande)
npm run phase-b:init
# équivalent : migrate puis docker compose --profile http up -d --build
# démarrages suivants ou après git pull (sans changement de schéma)
npm run phase-b:up
```
Redis est **interne Docker uniquement** (pas de port 6379 sur l’hôte) et protégé par `REDIS_PASSWORD` dans `.env` (obligatoire). En cas d’incident Redis (`Stream isn't writeable…`, `Connection is closed`, `READONLY`) : suivre le runbook **[REDIS-RUNBOOK.md](./REDIS-RUNBOOK.md)** (détails : [TROUBLESHOOTING-REDIS-PORT.md](./TROUBLESHOOTING-REDIS-PORT.md)).
Accès : **http://prediqo.redirectme.net:9080** (avec le port, en **http**)
### Parcours B — HTTPS avec Let’s Encrypt (recommandé)
Let’s Encrypt est **gratuit**. La validation **DNS** n’utilise pas les ports 80/443 du VPS.
#### Étape 1 — Certificat DNS (une fois, interactif)
```bash
npm run ssl:dns-init
```
Certbot affiche un enregistrement **TXT** à créer chez redirectme.net :
```
_acme-challenge.prediqo.redirectme.net → <valeur affichée>
```
Attendez 1–5 min (propagation DNS), puis validez dans le terminal.
#### Étape 2 — Démarrer la stack HTTPS
```bash
# 1er déploiement HTTPS (migrations + stack)
npm run phase-b:init:https
# équivalent : migrate puis docker compose --profile https-dns up -d --build
# démarrages suivants
npm run phase-b:up:https
```
Accès : **https://prediqo.redirectme.net:9443**
Le port **9080** redirige automatiquement vers **9443**.
---
## 6. Premier administrateur
> Résumé des commandes de démarrage : [section 4](#4-démarrage-sur-base-de-données-vierge-vps-et-local).
1. Ouvrez la page **setup** (voir URLs ci-dessous).
2. Saisissez le **`INITIAL_SETUP_TOKEN`** (valeur de `.env` ou `.env.docker` — **identique** à celle du serveur, min. 16 caractères).
3. **Créez** le compte administrateur **ou** **promouvez** un utilisateur déjà inscrit via Register.
4. Le système génère automatiquement un **code de parrainage racine** pour ce super administrateur ; les nouveaux utilisateurs sans code de parrainage y seront rattachés.
5. Connectez-vous sur **`/login`**.
6. Activez le **2FA** (Profil) et **sauvegardez les recovery codes hors ligne** (coffre / impression). Sans ces codes, une perte du téléphone bloque le login admin.
7. **Recommandé :** créez ou promouvez un **second** administrateur / Super Admin dès que possible, pour ne pas dépendre d’un seul compte.
8. **Hot wallet (une fois)** — depuis la racine du dépôt :
```bash
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/seedHotWallets.js
```
Notez l’adresse TRON affichée (à financer plus tard pour les retraits). Puis :
```bash
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/verifyDepositAddresses.js
```
| Contexte | URL setup |
|----------|-----------|
| VPS HTTPS | `https://prediqo.redirectme.net:9443/setup` |
| VPS HTTP | `http://prediqo.redirectme.net:9080/setup` |
| Local Docker | `http://localhost:9080/setup` |
Ensuite, gérez les rôles depuis **Admin → Users**.
Si `setupEnabled` est `false` dans `/api/v1/setup/status`, vérifiez que `INITIAL_SETUP_TOKEN` est défini (32+ caractères recommandés) et redémarrez le backend :
```bash
docker compose restart backend
```
### Break-glass — reset d’urgence du 2FA Super Admin
Si le **seul** Super Admin a perdu Authenticator **et** les recovery codes, `/setup` ne peut plus créer d’admin et aucune API web ne doit contourner le 2FA.
**Mécanisme :** script CLI exécuté **sur le VPS via Docker** (même niveau de confiance que SSH + `.env`). Ce n’est **pas** une route HTTP.
#### Prérequis
1. `BREAK_GLASS_TOKEN` (≥ 32 caractères) dans le `.env` à la racine du dépôt.
2. Recréer / redémarrer les conteneurs backend pour injecter la variable (`npm run phase-b:up` ou `docker compose up -d --build backend …`).
3. Connaître l’**e-mail** du Super Admin bloqué.
#### Commande (VPS)
```bash
cd ~/projects_repository/game-project # adaptez le chemin
# Charger le token depuis .env (ou le coller manuellement — ne le committez pas)
set -a && source .env && set +a
sudo docker compose run --rm --no-deps --build backend \
node dist/scripts/breakGlassResetAdmin2fa.js \
--email=admin@example.com \
--confirm=RESET_ADMIN_2FA \
--token="$BREAK_GLASS_TOKEN" \
--operator=votre-nom
```
Équivalent npm :
```bash
npm run phase-b:break-glass-reset-2fa -- \
--email=admin@example.com \
--confirm=RESET_ADMIN_2FA \
--token="$BREAK_GLASS_TOKEN" \
--operator=votre-nom
```
(`--confirm` doit être **exactement** `RESET_ADMIN_2FA`.)
#### Effets
- Efface le secret TOTP et les recovery codes du Super Admin ciblé
- Invalide les JWT (`token_version`) et supprime les refresh tokens
- Efface le lockout de login
- Force `require_admin_2fa=true` (ré-enrôlement obligatoire avant les APIs admin)
- Écrit un audit `break_glass_admin_2fa_reset` + notification e-mail / in-app
- **Cooldown 24 h** entre deux break-glass (toute la plateforme)
#### Après le reset
1. Connexion avec **e-mail + mot de passe** uniquement.
2. Profil → réactiver le 2FA → sauvegarder les **nouveaux** recovery codes.
3. Créer un second Super Admin si ce n’est pas déjà fait.
Si `/profile` affiche « Failed to load profile » alors que le login fonctionne, l’e-mail chiffré en base ne se déchiffre plus (souvent après changement d’`ENCRYPTION_KEY`). Mettez l’ancienne clé dans :
```env
ENCRYPTION_KEY_PREVIOUS=<ancienne_cle_64_hex>
```
puis redémarrez le backend, ou déployez le correctif qui laisse `/me` charger même si le decrypt PII échoue (pour pouvoir réactiver le 2FA). Ensuite `npm run phase-b:…` / rebuild backend (+ rebuild `prediqo-web` si vous tirez le fix UI).
#### Sécurité
| À faire | À éviter |
|---------|----------|
| Garder `BREAK_GLASS_TOKEN` hors git, dans le password manager | Exposer un endpoint HTTP « unlock 2FA » |
| Utiliser un token ≠ `JWT_SECRET` / `INITIAL_SETUP_TOKEN` | Réutiliser `INITIAL_SETUP_TOKEN` pour le break-glass |
| Laisser `BREAK_GLASS_TOKEN` vide tant que non nécessaire | Partager le token dans un chat |
Local Docker : `npm run docker:local:break-glass-reset-2fa -- …` (fichier `.env.docker`).
---
## 7. Commandes utiles
| Action | Commande |
|--------|----------|
| **1er déploiement HTTP (VPS)** | `npm run phase-b:init` |
| **1er déploiement HTTPS (VPS)** | `npm run phase-b:init:https` |
| **1er démarrage local Docker** | `npm run docker:local:init` |
| Démarrer / rebuild (HTTP VPS) | `npm run phase-b:up` |
| Démarrer / rebuild (HTTPS + gateway) | `npm run phase-b:up:https` (redémarre aussi `vps_gateway_nginx` s’il existe) |
| Démarrer local Docker | `npm run docker:local:up` |
| Migrations seules (VPS) | `npm run db:migrate` |
| Migrations seules (local Docker) | `npm run docker:local:migrate` |
| État des conteneurs | `npm run phase-b:status` |
| Logs en direct | `npm run phase-b:logs` |
| Redémarrer | `npm run phase-b:restart` |
| Recharger la passerelle 80/443 | `npm run gateway:reload` (si login/API en 502 après rebuild) |
| Démarrer la surveillance VPS | `npm run monitoring:up` (profile `monitoring`, pas de ports publics) |
| Arrêter | `npm run phase-b:down` |
| Remise à zéro DB | [§4.1](#41-remise-à-zéro--supprimer-et-recréer-la-base-avant-tests-réels) |
| Seed hot wallets (TRON + BSC) | `docker compose run --rm --no-deps backend node dist/scripts/seedHotWallets.js` |
| Vérifier adresses HD | `npm run phase-b:verify-deposit-addresses` |
| Smoke règles d’approbation (sans on-chain) | `sudo docker compose run --rm --no-deps backend node dist/scripts/smokeApprovalPolicies.js` |
| Reconstruire après changement `VITE_*` | `npm run phase-b:up` (HTTP) ou `phase-b:up:https` |
Logs d’un service précis :
```bash
docker compose logs -f backend
docker compose logs -f nginx-https-dns
```
---
## 8. Mise à jour après `git pull`
```bash
cd ~/games_app
git pull
npm run phase-b:up:https
# Vérifier : curl -sS https://tloto.net/health → doit renvoyer {"status":"ok",...}
```
### Surveillance VPS (back-office)
Voir [VPS-MONITORING.md](./VPS-MONITORING.md). En bref :
```bash
sudo npm run monitoring:up
sudo npm run phase-b:up:https
```
Puis **Options → Surveillance VPS** (permission `admin.vps_monitor.view`).
### 502 Bad Gateway après rebuild (passerelle VPS)
Cause fréquente : `vps_gateway_nginx` a résolu `crypto_wallet_api` vers une **ancienne IP Docker**. Le front (`prediqo-web`) peut encore répondre, mais `/api` et `/health` renvoient 502.
- **Immédiat** : `sudo npm run gateway:reload` (ou `sudo docker restart vps_gateway_nginx`)
- **Prévention** : `phase-b:up` / `phase-b:up:https` redémarrent déjà le gateway ; le template `deploy/vps-gateway/nginx/prediqo.conf.template` utilise le DNS Docker (`resolver 127.0.0.11`) pour re-résoudre les upstreams. Après pull de ce fix : `cd deploy/vps-gateway && sudo docker compose up -d` (recharge les templates).
Si seul le backend a changé (pas le frontend) :
```bash
docker compose build backend backend-engine backend-ws backend-worker-bets
docker compose --profile https-dns up -d
```
---
## 9. Renouveler le certificat SSL (~tous les 90 jours)
```bash
npm run ssl:dns-renew
```
Même procédure TXT DNS que lors de la création initiale.
---
## 10. Architecture des conteneurs
| Conteneur | Rôle |
|-----------|------|
| `prediqo_nginx_https` | Entrée web (9080 → 9443 HTTPS) |
| `prediqo_web` | Frontend React (build Vite) |
| `crypto_wallet_api` | API REST `/api/v1` |
| `crypto_wallet_ws` | WebSocket `/ws/…` |
| `crypto_wallet_engine` | Moteur de jeux (Candle Predict) |
| `crypto_wallet_worker_bets` | Traitement async des paris |
| `crypto_wallet_redis` | Cache / files Redis |
PostgreSQL tourne **sur l’hôte**, pas dans Docker (sauf profil `docker-db` optionnel).
---
## 11. Dépannage
### `database "…" does not exist`
La base PostgreSQL n’a pas été créée sur l’hôte (le nom doit être celui de `POSTGRES_DB`, en général `games_platform_db`).
```bash
sudo -u postgres psql -c "CREATE DATABASE games_platform_db;"
sudo docker compose --profile http up -d
sudo docker compose logs backend --tail 20
curl http://127.0.0.1:9080/api/v1/setup/status
```
Remise à zéro complète : [§4.1](#41-remise-à-zéro--supprimer-et-recréer-la-base-avant-tests-réels).
### Migration échoue : `relation "users" does not exist`
Sur une **base vierge**, une version antérieure de `schema.sql` créait `user_roles` avant la table `users`. Mettez à jour le dépôt puis relancez :
```bash
cd ~/projects_repository/games-project
git pull
npm run phase-b:init
```
Si des objets partiels existent (migration interrompue manuellement), repartir d’une base vide est le plus simple :
```bash
sudo -u postgres psql -c "DROP DATABASE IF EXISTS games_platform_db;"
sudo -u postgres psql -c "CREATE DATABASE games_platform_db;"
npm run phase-b:init
```
*(Adaptez le nom de la base à `POSTGRES_DB` dans `.env`.)*
### Tables manquantes (`parserOpenTable` / relation does not exist)
La base existe mais les **migrations** n’ont pas été appliquées.
```bash
sudo npm run db:migrate
# ou : sudo docker compose run --rm --no-deps backend node dist/db/migrate.js
sudo docker compose --profile http up -d
curl http://127.0.0.1:9080/api/v1/setup/status
```
### Colonne manquante (`prediction_commissions_enabled does not exist`)
Le backend a été mis à jour (commissions par prédiction) mais **`schema.sql` n’a pas été réappliqué**.
`phase-b:up` rebuild le code ; il ne remplace pas un migrate explicite si le migrate au boot a échoué / été ignoré.
```bash
cd ~/projects_repository/games-project
git pull
sudo npm run db:migrate
# Doit afficher: Migrations completed successfully.
sudo docker compose --profile http up -d --build
# (ou profile https-dns selon votre setup)
sudo docker compose logs backend --tail 30
```
Vérification SQL (optionnel) :
```bash
sudo docker compose exec -T postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
"\d referral_program_settings"
```
Vous devez voir `prediction_commissions_enabled`.
### nginx : `host not found in upstream "backend"`
nginx démarre avant que le backend soit visible dans le DNS Docker. Mettez à jour le projet (`git pull`) — les templates nginx utilisent le résolveur Docker `127.0.0.11`. Puis :
```bash
sudo docker compose --profile http up -d --force-recreate nginx
```
### Backend redémarre en boucle (DB OK avec psql sur l’hôte)
1. Vérifiez l’erreur exacte :
```bash
sudo docker compose logs backend --tail 20
```
2. `DATABASE_URL` dans `.env` doit utiliser **`host.docker.internal`**, pas `localhost` :
```env
DATABASE_URL=postgresql://postgres:VOTRE_MDP@host.docker.internal:5432/games_platform_db
```
3. `POSTGRES_PASSWORD` doit être **identique** au mot de passe postgres (caractères spéciaux → encoder en URL si besoin).
4. Autorisez le réseau Docker dans `pg_hba.conf` (voir section PostgreSQL ci-dessus).
5. Logs nginx si le port 9080 ne répond toujours pas :
```bash
sudo docker compose logs nginx --tail 20
sudo ss -tlnp | grep 9080
```
### Page s’affiche mais connexion / API échoue
Le frontend est compilé avec les URLs `VITE_*` du `.env`. Si vous lancez en **HTTP :9080** mais que `.env` contient `https://...:9443`, le navigateur appelle le mauvais serveur.
Corrigez `.env`, puis **rebuild** :
```env
APP_PUBLIC_URL=http://prediqo.redirectme.net:9080
VITE_API_BASE_URL=http://prediqo.redirectme.net:9080
VITE_WS_URL=ws://prediqo.redirectme.net:9080/ws/v1/games/candle-predict
```
```bash
sudo npm run phase-b:up
```
Vérifiez l’API depuis le VPS :
```bash
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:9080/api/v1/setup/status
# attendu : 200
```
### `permission denied` sur `docker.sock`
L’utilisateur Linux n’a pas le droit d’utiliser Docker.
**Correctif durable (recommandé) :**
```bash
sudo usermod -aG docker $USER
# Puis se déconnecter et reconnecter au VPS (ou : newgrp docker)
docker ps # doit fonctionner sans sudo
```
**Contournement immédiat :**
```bash
sudo npm run ssl:dns-init
sudo npm run phase-b:up:https
```
> Ne mettez pas à jour npm global (`npm install -g npm`) — ce n’est pas lié à l’erreur Docker et nécessite les droits root.
### Le site ne répond pas
```bash
npm run phase-b:status
docker compose logs nginx-https-dns --tail 50
```
Vérifiez le pare-feu (`9443/tcp`) et le DNS.
### Erreur base de données
```bash
docker compose logs backend --tail 100
```
Vérifiez `POSTGRES_*` dans `.env` et que PostgreSQL accepte les connexions depuis Docker (`host.docker.internal`).
### Certificat SSL / nginx ne démarre pas
Le certificat doit exister avant `phase-b:up:https` :
```bash
docker volume ls | grep letsencrypt
npm run ssl:dns-init # si pas encore fait
```
### Page blanche ou API inaccessible
Les URLs `VITE_*` sont figées au **build** du frontend. Après modification :
```bash
npm run phase-b:up:https
```
### `INITIAL_SETUP_TOKEN` refusé
Vérifiez la variable dans `.env` racine et redémarrez l’API :
```bash
docker compose restart backend
```
### Prédiction single-candle échoue (auto / multi OK)
Le pari manuel **single** passe par une file Redis (`BET_ASYNC=true`) traitée par **`backend-worker-bets`**, puis une confirmation WebSocket. L’auto et le multi contournent ce flux (exécution directe ou synchrone).
**Cause fréquente (VPS)** : l’interface affichait encore « fenêtre ouverte » via WebSocket/Redis alors que le serveur avait déjà fermé la fenêtre → le pari manuel était rejeté (`Prediction window is closed`) sans message clair. L’auto (déclenchée par le moteur) et le multi (réponse HTTP immédiate) continuaient de fonctionner.
**Correctifs** : publication WS à la fermeture de fenêtre, statut UI basé sur l’horloge serveur, cache Redis n’écrase plus le statut, `BET_ASYNC` lu depuis `.env`.
**Vérifications sur le VPS :**
```bash
sudo docker compose ps backend-worker-bets backend-ws redis
sudo docker compose logs backend-worker-bets --tail 80
sudo docker compose logs backend-ws --tail 40
```
Le conteneur `crypto_wallet_worker_bets` doit être **Up** et les logs doivent afficher `[worker-bets] Consumer worker-1 ready`.
**Test rapide** — désactiver temporairement la file async (pari synchrone comme le multi) :
```bash
# Dans .env racine (docker-compose lit cette variable) :
BET_ASYNC=false
sudo docker compose up -d --build backend backend-worker-bets
```
Si le single fonctionne avec `BET_ASYNC=false`, le problème vient du worker ou du WebSocket.
**WebSocket** — le frontend doit être buildé avec la bonne URL (rebuild obligatoire après changement) :
```env
VITE_WS_URL=ws://prediqo.redirectme.net:9080/ws/v1/games/candle-predict
VITE_WS_ENABLED=true
```
Puis : `sudo npm run phase-b:up` (rebuild `prediqo-web`).
**Depuis la version récente**, le frontend interroge aussi l’API `GET /api/v1/games/candle-predict/bets/outcome/:idempotencyKey` en secours si le WebSocket ne confirme pas le pari à temps.
---
## 12. Migration vers un VPS dédié (futur)
Quand Prediqo aura son propre serveur :
1. Dans `.env` : `PREDIQO_HTTP_PORT=80`, `PREDIQO_HTTPS_PORT=443`
2. URLs sans port : `https://prediqo.redirectme.net`
3. `npm run ssl:init && npm run phase-b:up:ssl`
Aucune modification des autres projets n’est nécessaire.
---
## 13. Fichiers `.env` — rappel
| Fichier | Usage |
|---------|--------|
| **`.env` (racine)** | **VPS Docker** — fichier principal |
| **`.env.docker`** | **Local Docker** — copie de `.env.docker.example`, gitignored |
| `backend/.env` | Dev local Node seulement (sans Docker) |
| `prediqo_web/.env` | Dev frontend Vite seulement ; en Docker, `VITE_*` vient du `.env` racine |