games_app/docs/DEPLOY-VPS.md

40 KiB
Raw Blame History

Guide de déploiement Prediqo sur VPS

Ce guide décrit comment lancer Prediqo 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.

Remise à zéro (supprimer / recréer la base) avant tests dépôt/retrait : voir section 4.1.


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)

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

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).

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)
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 (ou RPC fiable)
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)
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)
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)

# 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 :

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é) :

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) :

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) :

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) :

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).

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 :

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 :

# 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'))"
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 :

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
BREAK_GLASS_TOKEN=…

Laissez vide pour désactiver le break-glass jusqu’à ce que vous en ayez besoin. Voir section Break-glass 2FA.

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@@! :

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 (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 :
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 → application « Mail », appareil « Prediqo VPS ».
  3. Copier les 16 caractères (sans espaces) dans .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="Prediqo" <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) :

sudo npm run phase-b:verify-smtp

Puis redémarrer le backend :

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 :

sudo -u postgres psql -c "CREATE DATABASE games_platform_db;"

Si votre utilisateur PostgreSQL n’est pas postgres, adaptez :

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 :

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) :

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 :

sudo systemctl reload postgresql

Test depuis un conteneur :

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.

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é

  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. Après déploiement du fix scanner : le monitor détecte un solde unpaid et re-scanne (~7 j). Sinon crédit manuel :
sudo docker compose run --rm --no-deps --build backend \
  node dist/scripts/creditBscDepositByTx.js \
  --tx=0xVOTRE_TX_HASH
  1. Logs backend : [deposit] USDT_BEP20 / [deposit] credited USDT_BEP20.

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 :

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.

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/) :

cp .env.example .env
# Éditer .env : PostgreSQL, secrets, INITIAL_SETUP_TOKEN, URLs publiques

Premier déploiement (base vierge) — migrations + stack :

# 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) :

# 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) :

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é).

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) :

npm run docker:local:init

Équivalent :

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

Démarrages suivants :

npm run docker:local:up

Migrations seules (après git pull avec changement de schéma) :

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 :

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) :

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).

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
# 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

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)

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

# 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.

  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 :
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 :

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 :

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)

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 :

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 :

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 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
Arrêter npm run phase-b:down
Remise à zéro DB §4.1
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
Reconstruire après changement VITE_* npm run phase-b:up (HTTP) ou phase-b:up:https

Logs d’un service précis :

docker compose logs -f backend
docker compose logs -f nginx-https-dns

8. Mise à jour après git pull

cd ~/games_app
git pull
npm run phase-b:up:https

Si seul le backend a changé (pas le frontend) :

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)

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).

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.

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 :

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 :

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.

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é.

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) :

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 :

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 :
sudo docker compose logs backend --tail 20
  1. DATABASE_URL dans .env doit utiliser host.docker.internal, pas localhost :
DATABASE_URL=postgresql://postgres:VOTRE_MDP@host.docker.internal:5432/games_platform_db
  1. POSTGRES_PASSWORD doit être identique au mot de passe postgres (caractères spéciaux → encoder en URL si besoin).

  2. Autorisez le réseau Docker dans pg_hba.conf (voir section PostgreSQL ci-dessus).

  3. Logs nginx si le port 9080 ne répond toujours pas :

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 :

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
sudo npm run phase-b:up

Vérifiez l’API depuis le VPS :

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é) :

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 :

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

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

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 :

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 :

npm run phase-b:up:https

INITIAL_SETUP_TOKEN refusé

Vérifiez la variable dans .env racine et redémarrez l’API :

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 :

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) :

# 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) :

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