games_app/docs/DEPLOY-VPS.md
2026-07-02 10:56:38 +02:00

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


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

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

Créez la base si nécessaire :

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

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 crypto_wallet OWNER votre_user;"

Vérifiez la connexion :

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

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 :

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 "crypto_wallet" does not exist

→ le backend et nginx redémarrent en boucle, le port 9080 ne répond pas.


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


5. Premier administrateur

  1. Ouvrez https://prediqo.redirectme.net:9443/setup (ou :9080 en HTTP).
  2. Saisissez le INITIAL_SETUP_TOKEN (valeur de .env sur le serveur).
  3. Créez le compte admin ou promouvez un utilisateur existant.
  4. Connectez-vous sur /login.

Ensuite, gérez les rôles depuis Admin → Users.


6. Commandes utiles

Action Commande
1er déploiement HTTP npm run phase-b:init
1er déploiement HTTPS npm run phase-b:init:https
Démarrer / rebuild (HTTP) npm run phase-b:up
Migrations seules npm run db: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 :

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

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

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


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


10. Dépannage

database "crypto_wallet" does not exist

La base PostgreSQL n’a pas été créée sur l’hôte.

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

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

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.


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


12. Fichiers .env — rappel

Fichier VPS Docker
.env (racine) Oui — fichier principal
backend/.env Non requis (dev local Node seulement)
prediqo_web/.env Non requis (Docker utilise VITE_* du .env racine)