veza/veza-docs/vision/domains/backend/local-deployment-guide.md

id	title	sidebar_label
local-deployment-guide	Guide de Déploiement Local - Veza Platform	Guide de Déploiement Local - Veza Platform

NOTE: Cette page décrit la CIBLE (but visé).

Guide de Déploiement Local - Veza Platform

Vue d'ensemble

Ce guide te permet de déployer Veza localement sur ton PC pour tester avant le déploiement production final. Le déploiement local utilise Docker et Docker Compose pour simuler un environnement de production complet.

Prérequis

🖥️ Système

• OS : Linux, macOS, ou Windows (avec WSL2)
• RAM : Minimum 8GB (recommandé 16GB)
• Stockage : 10GB d'espace libre
• CPU : 4 cœurs minimum

🛠️ Logiciels Requis

Docker

# Ubuntu/Debian
sudo apt update
sudo apt install docker.io docker-compose

# macOS
brew install docker docker-compose

# Windows (WSL2)
# Installer Docker Desktop depuis https://www.docker.com/products/docker-desktop

Go

# Ubuntu/Debian
sudo apt install golang-go

# macOS
brew install go

# Windows
# Télécharger depuis https://golang.org/dl/

Rust

# Tous les systèmes
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

🔧 Vérification des Prérequis

# Vérifier Docker
docker --version
docker-compose --version

# Vérifier Go
go version

# Vérifier Rust
cargo --version

Déploiement Rapide

🚀 Démarrage Automatique

Le script de déploiement local automatise tout le processus :

# Rendre le script exécutable
chmod +x scripts/local-deployment.sh

# Démarrer tous les services
./scripts/local-deployment.sh start

📊 Vérification du Déploiement

# Vérifier le statut des services
./scripts/local-deployment.sh status

# Vérifier la santé des services
./scripts/local-deployment.sh health

# Voir les logs
./scripts/local-deployment.sh logs all

Architecture Locale

graph TB
    subgraph "Services Applicatifs"
        Backend[Backend API<br/>Port 8080]
        Chat[Chat Server<br/>Port 3001]
        Stream[Stream Server<br/>Port 3002]
    end
    
    subgraph "Infrastructure"
        Postgres[(PostgreSQL<br/>Port 5432)]
        Redis[(Redis<br/>Port 6379)]
    end
    
    subgraph "Monitoring"
        Prometheus[Prometheus<br/>Port 9090]
        Grafana[Grafana<br/>Port 3000]
        Elasticsearch[Elasticsearch<br/>Port 9200]
        Kibana[Kibana<br/>Port 5601]
    end
    
    Backend --> Postgres
    Backend --> Redis
    Chat --> Postgres
    Chat --> Redis
    Stream --> Postgres
    Stream --> Redis
    
    Backend --> Prometheus
    Chat --> Prometheus
    Stream --> Prometheus
    
    Prometheus --> Grafana
    Elasticsearch --> Kibana

Services Disponibles

🔧 Services Applicatifs

Service	Port	URL	Description
Backend API	8080	http://localhost:8080	API principale
Chat Server	3001	http://localhost:3001	Service de chat temps réel
Stream Server	3002	http://localhost:3002	Service de streaming

📊 Services de Monitoring

Service	Port	URL	Credentials
Grafana	3000	http://localhost:3000	admin/admin
Prometheus	9090	http://localhost:9090	-
Kibana	5601	http://localhost:5601	-
Elasticsearch	9200	http://localhost:9200	-

🗄️ Services d'Infrastructure

Service	Port	Description
PostgreSQL	5432	Base de données principale
Redis	6379	Cache et sessions

Commandes Utiles

🎮 Gestion des Services

# Démarrer tous les services
./scripts/local-deployment.sh start

# Arrêter tous les services
./scripts/local-deployment.sh stop

# Redémarrer tous les services
./scripts/local-deployment.sh restart

# Voir le statut
./scripts/local-deployment.sh status

# Vérifier la santé
./scripts/local-deployment.sh health

📝 Logs et Debugging

# Tous les logs
./scripts/local-deployment.sh logs all

# Logs d'un service spécifique
./scripts/local-deployment.sh logs backend
./scripts/local-deployment.sh logs chat
./scripts/local-deployment.sh logs stream
./scripts/local-deployment.sh logs postgres
./scripts/local-deployment.sh logs redis
./scripts/local-deployment.sh logs grafana
./scripts/local-deployment.sh logs prometheus

🧹 Nettoyage

# Nettoyage complet (supprime toutes les données)
./scripts/local-deployment.sh clean

Tests Locaux

🔍 Tests de Base

# Test Backend API
curl http://localhost:8080/health

# Test Chat Server
curl http://localhost:3001/health

# Test Stream Server
curl http://localhost:3002/health

# Test PostgreSQL
docker exec veza-postgres-local pg_isready -U veza_user -d veza_local

# Test Redis
docker exec veza-redis-local redis-cli ping

🧪 Tests API

# Test d'authentification
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

# Test de création d'utilisateur
curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","username":"testuser","password":"password123"}'

# Test de création de room
curl -X POST http://localhost:8080/api/v1/chat/rooms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"name":"Test Room","description":"Room de test"}'

📊 Tests de Monitoring

# Test Prometheus
curl http://localhost:9090/api/v1/targets

# Test Grafana
curl http://localhost:3000/api/health

# Test Elasticsearch
curl http://localhost:9200/_cluster/health

# Test Kibana
curl http://localhost:5601/api/status

Configuration Avancée

🔧 Variables d'Environnement

Les services utilisent les variables d'environnement suivantes :

# Backend API
DATABASE_URL=postgresql://veza_user:veza_password@postgres:5432/veza_local
REDIS_URL=redis://redis:6379
JWT_SECRET=local-jwt-secret-key

# Chat Server
DATABASE_URL=postgresql://veza_user:veza_password@postgres:5432/veza_local
REDIS_URL=redis://redis:6379

# Stream Server
DATABASE_URL=postgresql://veza_user:veza_password@postgres:5432/veza_local
REDIS_URL=redis://redis:6379

📁 Structure des Fichiers

veza-backend-api/
├── scripts/
│   └── local-deployment.sh    # Script de déploiement
├── config/
│   ├── prometheus.yml         # Configuration Prometheus
│   └── grafana/              # Configuration Grafana
├── Dockerfile.backend        # Dockerfile Backend
├── Dockerfile.chat           # Dockerfile Chat
├── Dockerfile.stream         # Dockerfile Stream
└── docker-compose.local.yml  # Configuration Docker Compose

Monitoring et Observabilité

📊 Grafana Dashboards

1. Ouvrir Grafana : http://localhost:3000
2. Se connecter : admin/admin
3. Dashboards disponibles :
   • System Overview
   • Application Metrics
   • Database Performance
   • Network Metrics

📈 Prometheus Metrics

1. Ouvrir Prometheus : http://localhost:9090
2. Métriques disponibles :
   • http_requests_total
   • http_request_duration_seconds
   • up
   • process_cpu_seconds_total

📝 Logs avec Kibana

1. Ouvrir Kibana : http://localhost:5601
2. Index patterns : filebeat-*
3. Logs disponibles :
   • Application logs
   • System logs
   • Error logs

Dépannage

🔍 Problèmes Courants

Services ne démarrent pas

# Vérifier les logs
./scripts/local-deployment.sh logs all

# Vérifier l'espace disque
df -h

# Vérifier la mémoire
free -h

# Redémarrer Docker
sudo systemctl restart docker

Erreurs de base de données

# Vérifier PostgreSQL
docker exec veza-postgres-local pg_isready -U veza_user -d veza_local

# Réinitialiser la base de données
docker-compose -f docker-compose.local.yml down
docker volume rm veza-full-stack_postgres_data
./scripts/local-deployment.sh start

Erreurs de réseau

# Vérifier les ports
netstat -tulpn | grep -E ':(8080|3001|3002|5432|6379|3000|9090)'

# Vérifier Docker network
docker network ls
docker network inspect veza-full-stack_veza-network

🛠️ Debugging Avancé

Inspection des Conteneurs

# Voir les conteneurs en cours
docker ps -a

# Inspecter un conteneur
docker inspect veza-backend-local

# Exécuter une commande dans un conteneur
docker exec -it veza-backend-local sh

Logs Détaillés

# Logs avec timestamps
docker logs -t veza-backend-local

# Logs des 100 dernières lignes
docker logs --tail 100 veza-backend-local

# Logs en temps réel
docker logs -f veza-backend-local

Performance et Optimisation

⚡ Optimisations Locales

Ressources Docker

# Augmenter la mémoire Docker (macOS/Windows)
# Docker Desktop > Settings > Resources > Memory: 8GB

# Augmenter les CPUs Docker
# Docker Desktop > Settings > Resources > CPUs: 4

Configuration PostgreSQL

# Optimiser PostgreSQL pour le développement
docker exec -it veza-postgres-local psql -U veza_user -d veza_local -c "
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET effective_cache_size = '1GB';
ALTER SYSTEM SET maintenance_work_mem = '64MB';
ALTER SYSTEM SET checkpoint_completion_target = 0.9;
ALTER SYSTEM SET wal_buffers = '16MB';
ALTER SYSTEM SET default_statistics_target = 100;
SELECT pg_reload_conf();
"

📊 Monitoring des Performances

Métriques Système

# Utilisation CPU
docker stats

# Utilisation mémoire
docker stats --no-stream

# Utilisation disque
docker system df

Migration vers Production

🔄 Préparation Production

Une fois les tests locaux validés, voici les étapes pour migrer vers la production :

1. Optimiser les configurations

   • Ajuster les variables d'environnement
   • Configurer les secrets de production
   • Optimiser les paramètres de performance

2. Préparer l'infrastructure

   • Configurer les serveurs de production
   • Mettre en place le monitoring
   • Configurer les sauvegardes

3. Déployer progressivement

   • Déploiement en staging
   • Tests de charge
   • Déploiement en production

📋 Checklist Production

• Tests locaux validés
• Configurations de production préparées
• Infrastructure mise en place
• Monitoring configuré
• Sauvegardes configurées
• Sécurité validée
• Documentation mise à jour

---

Dernière mise à jour : Décembre 2024
Version : 1.0.0
Statut : Production Ready ✅