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

---
id: "local-deployment-guide"
title: "Guide de Déploiement Local - Veza Platform"
sidebar_label: "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
```bash
# 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
```bash
# Ubuntu/Debian
sudo apt install golang-go

# macOS
brew install go

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

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

### 🔧 Vérification des Prérequis
```bash
# 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 :

```bash
# 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

```bash
# 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

```mermaid
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

```bash
# 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

```bash
# 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

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

## Tests Locaux

### 🔍 Tests de Base

```bash
# 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

```bash
# 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

```bash
# 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 :

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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 ✅