977 lines
31 KiB
Markdown
977 lines
31 KiB
Markdown
# 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](#4-démarrage-sur-base-de-données-vierge-vps-et-local).
|
||
|
||
---
|
||
|
||
## 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 |
|
||
| `JWT_SECRET` | Secret JWT (32+ caractères aléatoires) |
|
||
| `ENCRYPTION_KEY` | 64 caractères hex (32 octets AES-256) |
|
||
| `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 pour reset 2FA Super Admin (CLI Docker uniquement, min 32 car.) |
|
||
| `APP_PUBLIC_URL` | `https://prediqo.redirectme.net:9443` |
|
||
| `VITE_API_BASE_URL` | même URL de base (sans `/api`) |
|
||
| `VITE_WS_URL` | `wss://prediqo.redirectme.net:9443/ws/v1/games/candle-predict` |
|
||
| `CERTBOT_EMAIL` | Email pour Let’s Encrypt |
|
||
| `CERTBOT_DOMAIN1` | `prediqo.redirectme.net` |
|
||
| `SMTP_*` / `EMAIL_FROM` | Envoi d’emails (vérification compte, 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 le hot wallet existe déjà, le script affiche `Skipping` et ne recrée rien.
|
||
|
||
#### 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 USDT
|
||
sudo docker compose run --rm --no-deps --build backend \
|
||
node dist/scripts/rotateDepositAddresses.js \
|
||
--confirm=ROTATE_DEPOSIT_ADDRESSES \
|
||
--scope=existing
|
||
|
||
# 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
|
||
```
|
||
|
||
Équivalent : `npm run phase-b:rotate-deposit-addresses -- --confirm=ROTATE_DEPOSIT_ADDRESSES --scope=existing`
|
||
|
||
Le script ne touche **pas** au hot wallet 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.
|
||
|
||
#### `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="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`) :**
|
||
|
||
```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**
|
||
|
||
Créez la base si nécessaire :
|
||
|
||
```bash
|
||
sudo -u postgres psql -c "CREATE DATABASE crypto_wallet;"
|
||
```
|
||
|
||
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 crypto_wallet OWNER votre_user;"
|
||
```
|
||
|
||
Vérifiez la connexion :
|
||
|
||
```bash
|
||
psql -U postgres -h localhost -d crypto_wallet -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
|
||
|
||
# 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 "crypto_wallet" 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 à exécuter lorsque PostgreSQL est **vide** (base créée, mais **sans schéma**). L’ordre est toujours le même :
|
||
|
||
1. **Créer la base** PostgreSQL (voir section 3).
|
||
2. **Configurer** les secrets et `INITIAL_SETUP_TOKEN` dans le fichier d’environnement.
|
||
3. **Appliquer les migrations** (création des tables).
|
||
4. **Démarrer la stack** (API, frontend, Redis, workers…).
|
||
5. **Configurer la plateforme** via la page **`/setup`** (premier super administrateur).
|
||
|
||
> Les scripts `*:init` enchaînent automatiquement **migrations + démarrage** en une seule commande.
|
||
|
||
### Prérequis communs
|
||
|
||
| Étape | Détail |
|
||
|-------|--------|
|
||
| Base PostgreSQL | Base vide créée (`games_platform_db` ou `crypto_wallet` 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}
|
||
```
|
||
|
||
### 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
|
||
```
|
||
|
||
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.
|
||
|
||
| 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.
|
||
|
||
#### 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` |
|
||
| Reconstruire après changement `VITE_*` | `npm run 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
|
||
```
|
||
|
||
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 "crypto_wallet" does not exist`
|
||
|
||
La base PostgreSQL n’a pas été créée sur l’hôte.
|
||
|
||
```bash
|
||
sudo -u postgres psql -c "CREATE DATABASE crypto_wallet;"
|
||
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
|
||
```
|
||
|
||
### 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 |
|