Fix fresh-DB migration order for candle_predict_auto_settings, fail loudly on migrate errors, honor DATABASE_URL from .env, add Docker DNS resolver for nginx upstreams, and document VPS deploy steps. Co-authored-by: Cursor <cursoragent@cursor.com>
12 KiB
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) |
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
npm run phase-b:up
# équivalent : docker compose --profile http up -d --build
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
npm run phase-b:up:https
# équivalent : docker compose --profile https-dns up -d --build
Accès : https://prediqo.redirectme.net:9443
Le port 9080 redirige automatiquement vers 9443.
5. Premier administrateur
- Ouvrez https://prediqo.redirectme.net:9443/setup (ou
:9080en HTTP). - Saisissez le
INITIAL_SETUP_TOKEN(valeur de.envsur le serveur). - Créez le compte admin ou promouvez un utilisateur existant.
- Connectez-vous sur /login.
Ensuite, gérez les rôles depuis Admin → Users.
6. Commandes utiles
| Action | Commande |
|---|---|
| É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)
- Vérifiez l’erreur exacte :
sudo docker compose logs backend --tail 20
DATABASE_URLdans.envdoit utiliserhost.docker.internal, paslocalhost:
DATABASE_URL=postgresql://postgres:VOTRE_MDP@host.docker.internal:5432/games_platform_db
-
POSTGRES_PASSWORDdoit être identique au mot de passe postgres (caractères spéciaux → encoder en URL si besoin). -
Autorisez le réseau Docker dans
pg_hba.conf(voir section PostgreSQL ci-dessus). -
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
11. Migration vers un VPS dédié (futur)
Quand Prediqo aura son propre serveur :
- Dans
.env:PREDIQO_HTTP_PORT=80,PREDIQO_HTTPS_PORT=443 - URLs sans port :
https://prediqo.redirectme.net 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) |