1273 lines
50 KiB
Markdown
1273 lines
50 KiB
Markdown
# 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 (Gmail)
|
||
|
||
L’erreur `535-5.7.8 Username and Password not accepted` signifie que **Gmail refuse le mot de passe SMTP**. Le mot de passe normal du compte Gmail **ne fonctionne pas** : il faut un **mot de passe d’application**.
|
||
|
||
1. Activer la **validation en 2 étapes** sur le compte Gmail expéditeur.
|
||
2. Créer un mot de passe d’application : [https://myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords) → application « Mail », appareil « Prediqo VPS ».
|
||
3. Copier les **16 caractères** (sans espaces) dans `.env` :
|
||
|
||
```env
|
||
EMAIL_TRANSPORT=smtp
|
||
SMTP_HOST=smtp.gmail.com
|
||
SMTP_PORT=587
|
||
SMTP_SECURE=false
|
||
SMTP_USER=votre-compte@gmail.com
|
||
SMTP_PASS=xxxxxxxxxxxxxxxx
|
||
EMAIL_FROM="Tloto" <votre-compte@gmail.com>
|
||
APP_PUBLIC_URL=https://prediqo.redirectme.net:9443
|
||
RESET_PASSWORD_PATH=/reset-password
|
||
```
|
||
|
||
`SMTP_USER` doit être **le même compte Gmail** que celui qui a généré le mot de passe d’application.
|
||
|
||
**Tester la connexion SMTP (après `git pull`) :**
|
||
|
||
```bash
|
||
sudo npm run phase-b:verify-smtp
|
||
```
|
||
|
||
Puis redémarrer le backend :
|
||
|
||
```bash
|
||
sudo npm run phase-b:up
|
||
```
|
||
|
||
> **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) |
|
||
| 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",...}
|
||
```
|
||
|
||
### 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 |
|