Déploiement VPS KoproGo (1 vCPU / 2GB RAM)

Guide de déploiement pour un VPS à ressources limitées (1 vCPU, 2GB RAM).

Table des matières

Prérequis
Configuration du VPS
Configuration de l’application
Déploiement
Monitoring
Tests de charge
Optimisations appliquées
Maintenance

Prérequis

VPS avec 1 vCPU et 2GB RAM minimum
Ubuntu 22.04 LTS ou Debian 12
Nom de domaine configuré avec DNS pointant vers le VPS
Accès SSH root ou sudo

Configuration du VPS

1. Installation des dépendances

# Mise à jour du système
apt update && apt upgrade -y

# Installation de Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Installation de Docker Compose
apt install docker-compose-plugin -y

# Installation des outils de monitoring
apt install htop iotop ncdu -y

2. Configuration du swap (recommandé pour 2GB RAM)

# Créer un fichier swap de 2GB
fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

# Rendre le swap permanent
echo '/swapfile none swap sw 0 0' >> /etc/fstab

# Optimiser l'usage du swap (swappiness=10 pour limiter l'usage)
echo 'vm.swappiness=10' >> /etc/sysctl.conf
sysctl -p

3. Sécurisation SSH

# Désactiver l'accès root (après avoir créé un utilisateur sudo)
sed -i 's/PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config

# Désactiver l'authentification par mot de passe (utiliser des clés SSH)
sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config

systemctl restart sshd

4. Configuration du pare-feu

# Installation d'ufw
apt install ufw -y

# Configuration des règles
ufw allow ssh
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Configuration de l’application

1. Cloner le dépôt

cd /opt
git clone https://github.com/votre-org/koprogo.git
cd koprogo

2. Créer le fichier d’environnement

cp .env.example .env.vps

3. Éditer `.env.vps` avec vos valeurs

# Variables critiques à modifier
POSTGRES_PASSWORD=VOTRE_MOT_DE_PASSE_SECURISE
JWT_SECRET=VOTRE_CLE_SECRETE_LONGUE_ET_ALEATOIRE_MIN_32_CHARS

# Domaines
FRONTEND_DOMAIN=app.votredomaine.com
API_DOMAIN=api.votredomaine.com
TRAEFIK_DOMAIN=traefik.votredomaine.com

# Email pour Let's Encrypt
ACME_EMAIL=admin@votredomaine.com

# CORS
CORS_ORIGIN=https://app.votredomaine.com

# Auth Traefik Dashboard (générer avec: htpasswd -nb admin votre_mot_de_passe)
TRAEFIK_DASHBOARD_AUTH=admin:$apr1$...

# Logging (warn pour économiser les ressources)
RUST_LOG=warn
TRAEFIK_LOG_LEVEL=WARN

# Ressources (déjà optimisées dans docker-compose.vps.yml)
ACTIX_WORKERS=1
DB_POOL_MAX_CONNECTIONS=8
DB_POOL_MIN_CONNECTIONS=2

4. Générer un mot de passe sécurisé pour Traefik

# Installer apache2-utils pour htpasswd
apt install apache2-utils -y

# Générer le hash (remplacer 'votre_mot_de_passe')
htpasswd -nb admin votre_mot_de_passe

Déploiement

1. Build des images

docker compose -f docker-compose.vps.yml --env-file .env.vps build

2. Démarrage des services

docker compose -f docker-compose.vps.yml --env-file .env.vps up -d

3. Vérifier les logs

# Tous les services
docker compose -f docker-compose.vps.yml logs -f

# Service spécifique
docker compose -f docker-compose.vps.yml logs -f backend
docker compose -f docker-compose.vps.yml logs -f postgres
docker compose -f docker-compose.vps.yml logs -f traefik

4. Vérifier l’état des services

docker compose -f docker-compose.vps.yml ps

Tous les services doivent être healthy :

NAME                 STATUS          PORTS
koprogo-traefik      Up 2 minutes    0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp
koprogo-postgres     Up 2 minutes    (healthy)
koprogo-backend      Up 2 minutes    (healthy)
koprogo-frontend     Up 2 minutes    (healthy)

Monitoring

1. Vérifier l’usage mémoire

# Vue globale
free -h

# Par container
docker stats

2. Vérifier l’usage CPU

htop

3. Dashboard Traefik

Accéder à https://traefik.votredomaine.com/dashboard/

Username: admin
Password: celui que vous avez configuré

4. Logs applicatifs

# Backend API
docker compose -f docker-compose.vps.yml logs backend --tail=100 -f

# PostgreSQL
docker compose -f docker-compose.vps.yml logs postgres --tail=100 -f

5. Healthchecks

# API health
curl https://api.votredomaine.com/api/v1/health

# Frontend health
curl https://app.votredomaine.com/health

Tests de charge

Après le déploiement, il est recommandé de valider les performances du système avec des tests de charge.

⚠️ Important : Tests à distance

Les tests de charge doivent être lancés depuis une machine externe (votre ordinateur ou un autre VPS), PAS depuis le VPS serveur lui-même.

Raisons :

Les tests consomment CPU/RAM et faussent les résultats
Pas de latence réseau en localhost
Conditions irréalistes

→ Voir la documentation complète : load-tests/REMOTE_TESTING.md

Setup rapide (machine cliente)

Sur votre machine locale ou un VPS client :

# Cloner le repo
git clone https://github.com/votre-org/koprogo.git
cd koprogo/load-tests

# Installer wrk
# Ubuntu/Debian:
sudo apt-get install wrk

# macOS:
brew install wrk

Tests disponibles

Le projet inclut une suite complète de tests de charge dans load-tests/ :

Test	Durée	Charge	Objectif
warmup	30s	Très légère	Préparer le système (toujours lancer en premier)
light-load	2 min	100 req/s	Valider le fonctionnement normal
medium-load	5 min	500 req/s	Tester les pics de charge
heavy-load	3 min	1000 req/s	Trouver le point de rupture
spike-test	5 min	Variable	Tester la résilience aux pics soudains
soak-test	30 min	Soutenue	Détecter les fuites mémoire

Lancement rapide

Sur la machine cliente (pas sur le VPS !) :

cd koprogo/load-tests

# Par défaut, les scripts ciblent https://api.koprogo.com
# Aucune configuration nécessaire !
./scripts/remote-light-load.sh
./scripts/remote-medium-load.sh

# Pour tester un autre domaine :
export BASE_URL=https://api.votredomaine.com
./scripts/remote-light-load.sh

En parallèle, sur le VPS (monitoring) :

# SSH vers le VPS
ssh user@vps-ip
cd /opt/koprogo/load-tests

# Monitorer pendant 5 minutes
./monitor-server.sh 300

Résultats attendus (1 vCPU / 2GB RAM)

Light Load ✅

P99 latency: < 50ms
Throughput: > 100 req/s
Error rate: < 0.1%
CPU usage: ~30-40%

Medium Load ✅

P99 latency: < 100ms
Throughput: > 500 req/s
Error rate: < 0.5%
CPU usage: ~70-80%

Heavy Load ⚠️

P99 latency: < 200ms (acceptable)
Throughput: Plateau possible
Error rate: < 5% (acceptable)
CPU usage: 95-100%

Monitoring pendant les tests

Terminal 1 : Machine cliente (lance les tests)

cd koprogo/load-tests
export BASE_URL=https://api.votredomaine.com
./scripts/remote-medium-load.sh

Terminal 2 : VPS serveur (monitoring automatique)

ssh user@vps-ip
cd /opt/koprogo/load-tests
./monitor-server.sh 300  # 5 minutes

Terminal 3 : VPS serveur (logs en temps réel)

ssh user@vps-ip
docker compose -f docker-compose.vps.yml logs -f backend | grep -E "(ERROR|WARN)"

Suite complète de tests

Machine cliente :

cd koprogo/load-tests
export BASE_URL=https://api.votredomaine.com

# Tests individuels
./scripts/remote-light-load.sh
./scripts/remote-medium-load.sh

# Résultats locaux
ls -lh results/

VPS serveur (récupérer les logs de monitoring) :

ssh user@vps-ip
cd /opt/koprogo/load-tests
ls -lh monitoring-results/

Documentation complète

Guide rapide : load-tests/QUICKSTART.md
Documentation détaillée : load-tests/README.md
Scripts de test : load-tests/scripts/

Troubleshooting des tests

Trop d’erreurs (> 5%)

Réduire le nombre de connexions dans les scripts
Vérifier les logs pour identifier les goulots d’étranglement
Augmenter DB_POOL_MAX_CONNECTIONS si nécessaire

Latence élevée (> 200ms)

Vérifier l’usage CPU (doit être < 95%)
Vérifier le swap (devrait être peu utilisé)
Analyser les requêtes lentes dans PostgreSQL

Out of Memory

Réduire shared_buffers PostgreSQL
Réduire DB_POOL_MAX_CONNECTIONS
Vérifier les fuites mémoire avec soak-test.sh

Optimisations appliquées

Allocation mémoire (Total: ~1.6GB + système)

Service	Limite RAM	Réservation	CPU Limit
Traefik	50MB	-	0.25
PostgreSQL	~256MB	-	-
Backend	384MB	256MB	0.75
Frontend	128MB	96MB	0.5

PostgreSQL (256MB alloués)

shared_buffers: 256MB (mémoire partagée)
effective_cache_size: 768MB (estimation du cache OS)
work_mem: 5MB (par opération de tri/hash)
maintenance_work_mem: 64MB (VACUUM, CREATE INDEX)
max_connections: 15 (limité pour économiser la RAM)
WAL optimisé pour SSD avec checksums

Backend Rust

1 worker Actix au lieu de 2
Pool de connexions DB: 8 max au lieu de 10
- min_connections: 2
- acquire_timeout: 30s
- idle_timeout: 10 minutes
- max_lifetime: 30 minutes
RUST_LOG=warn pour limiter les I/O de logs
Rate limiting: 100 req/s moyen, burst 200

Frontend

Nginx Alpine (léger)
Gzip compression activée
Cache des assets statiques (1 an)
128MB RAM limite

Logs

Rotation automatique configurée :

Taille max par fichier: 10MB
Nombre de fichiers: 3
Total max par service: ~30MB

Maintenance

Mise à jour de l’application

cd /opt/koprogo
git pull origin main

# Rebuild et redémarrage
docker compose -f docker-compose.vps.yml --env-file .env.vps build
docker compose -f docker-compose.vps.yml --env-file .env.vps up -d

Backup de la base de données

# Créer un backup
docker compose -f docker-compose.vps.yml exec postgres pg_dump -U koprogo koprogo_db > backup_$(date +%Y%m%d).sql

# Restaurer un backup
docker compose -f docker-compose.vps.yml exec -T postgres psql -U koprogo koprogo_db < backup_20250124.sql

Nettoyage Docker

# Supprimer les images inutilisées
docker image prune -a -f

# Supprimer les volumes inutilisés
docker volume prune -f

# Supprimer tout ce qui n'est pas utilisé
docker system prune -a --volumes -f

Vérifier l’espace disque

# Vue globale
df -h

# Par répertoire (interactif)
ncdu /

# Espace utilisé par Docker
docker system df

Renouvellement SSL (Let’s Encrypt)

Le renouvellement est automatique via Traefik. Les certificats sont stockés dans le volume traefik_letsencrypt.

Pour forcer un renouvellement :

docker compose -f docker-compose.vps.yml restart traefik

Surveillance des performances

# Statistiques en temps réel
docker stats

# Top des processus
htop

# I/O disque
iotop -o

Troubleshooting

Le backend ne démarre pas

Vérifier les logs :

docker compose -f docker-compose.vps.yml logs backend

Vérifier que PostgreSQL est healthy :

docker compose -f docker-compose.vps.yml ps postgres

Vérifier les migrations :

docker compose -f docker-compose.vps.yml exec backend ls -la /app/migrations

PostgreSQL est lent

Vérifier les connexions actives :

docker compose -f docker-compose.vps.yml exec postgres \
  psql -U koprogo -d koprogo_db -c "SELECT count(*) FROM pg_stat_activity;"

Vérifier la configuration :

docker compose -f docker-compose.vps.yml exec postgres \
  psql -U koprogo -d koprogo_db -c "SHOW shared_buffers; SHOW work_mem;"

Analyser les requêtes lentes :

docker compose -f docker-compose.vps.yml logs postgres | grep "duration"

Mémoire saturée

Vérifier l’usage :
```
free -h
docker stats --no-stream
```
Identifier le service problématique et ajuster les limites dans docker-compose.vps.yml
Vérifier le swap :
```
swapon --show
```

SSL ne fonctionne pas

Vérifier que les DNS pointent bien vers le VPS :

dig app.votredomaine.com
dig api.votredomaine.com

Vérifier les logs Traefik :

docker compose -f docker-compose.vps.yml logs traefik

Vérifier les ports 80 et 443 :

ufw status
netstat -tulpn | grep -E ':(80|443)'

Support

Pour toute question ou problème :

GitHub Issues : https://github.com/votre-org/koprogo/issues
Documentation : https://docs.koprogo.com