veza/MAKEFILE_GUIDE.md

Veza Makefile Guide

Ce Makefile fournit une interface complète pour gérer le projet Veza avec support Docker et Incus (LXD).

Organisation des Commandes

Les commandes sont organisées en trois niveaux :

🔴 HIGH LEVEL - Commandes de haut niveau

Commandes simples pour les tâches courantes :

• make setup - Initialisation complète du projet
• make stop-all - Arrêter tous les services
• make restart-all - Redémarrer tous les services
• make clean - Nettoyer les artefacts de build
• make deploy-docker - Déployer avec Docker + HAProxy
• make deploy-incus - Déployer avec Incus containers
• make status-full - Afficher le statut complet du système

🔵 INTERMEDIATE - Commandes intermédiaires

Commandes plus précises pour gérer des services individuels :

• make start-service SERVICE=backend-api - Démarrer un service
• make stop-service SERVICE=backend-api - Arrêter un service
• make restart-service SERVICE=backend-api - Redémarrer un service
• make logs-service SERVICE=backend-api - Voir les logs d'un service
• make build-service SERVICE=backend-api - Builder un service
• make build-all - Builder tous les services
• make infra-up - Démarrer l'infrastructure (Postgres, Redis, RabbitMQ)
• make db-migrate - Exécuter les migrations de base de données
• make db-shell - Accéder au shell Postgres
• make redis-shell - Accéder au shell Redis

🟣 LOW LEVEL / DEBUG - Commandes de bas niveau

Commandes pour le développement et le debug :

• make check-tools - Vérifier les outils requis
• make install-tools - Installer les outils de développement
• make install-deps - Installer les dépendances
• make check-ports - Vérifier la disponibilité des ports
• make incus-setup-network - Configurer le réseau Incus
• make incus-deploy-service SERVICE=backend-api - Déployer un service sur Incus
• make incus-logs SERVICE=backend-api - Voir les logs Incus

Déploiement Docker

Déploiement complet avec HAProxy

# Builder et déployer tous les services
make deploy-docker

Cela va :

1. Builder toutes les images Docker
2. Démarrer tous les services (infrastructure + applications)
3. Configurer HAProxy comme reverse proxy
4. Attendre que tous les services soient prêts

Accès :

• Frontend : http://localhost:80
• API : http://localhost:80/api/v1
• WebSocket Chat : ws://localhost:80/ws
• WebSocket Stream : ws://localhost:80/stream
• HAProxy Stats : http://localhost:8404/stats

Gestion des services individuels

# Démarrer un service
make start-service SERVICE=backend-api

# Arrêter un service
make stop-service SERVICE=backend-api

# Redémarrer un service
make restart-service SERVICE=backend-api

# Voir les logs
make logs-service SERVICE=backend-api

Déploiement Incus (LXD)

Prérequis

# Installer Incus
sudo snap install incus

# Initialiser Incus (première fois)
sudo incus admin init

Déploiement complet

# Déployer tous les services avec Incus
make deploy-incus

Cela va :

1. Créer le réseau Incus veza-network
2. Créer le profil veza-profile
3. Déployer chaque service dans un container Incus séparé
4. Installer Docker dans chaque container

Gestion des containers Incus

# Voir les logs d'un container
make incus-logs SERVICE=backend-api

# Arrêter tous les containers
make incus-stop-all

# Déployer un service spécifique
make incus-deploy-service SERVICE=backend-api

Architecture

Services

• backend-api : API Go (port 8080)
• chat-server : Serveur Chat Rust (port 3000)
• stream-server : Serveur Stream Rust (port 3001)
• web : Frontend React/Vite (port 5173)
• haproxy : Reverse Proxy (port 80)

Infrastructure

• postgres : Base de données PostgreSQL (port 5432)
• redis : Cache Redis (port 6379)
• rabbitmq : Message broker RabbitMQ (ports 5672, 15672)

Réseau

Tous les services communiquent via le réseau Docker veza-network (172.20.0.0/16).

Développement Local

Démarrer l'environnement de développement

# Démarrer tout (détecte automatiquement les outils de hot reload)
make dev

# Démarrer seulement les backends
make dev-backend

Le Makefile détecte automatiquement :

• air pour le hot reload Go
• cargo-watch pour le hot reload Rust
• Utilise le mode standard si les outils ne sont pas disponibles

Arrêter les services locaux

# Arrêter tous les processus locaux
make stop-local-services

Maintenance

Nettoyage

# Nettoyer les artefacts de build
make clean

# Nettoyage complet (demande confirmation)
make clean-deep

Statut

# Statut simple
make status

# Statut complet (Docker + Local + Incus)
make status-full

Tests

# Exécuter tous les tests
make test

# Linter le code
make lint

# Formater le code
make fmt

Configuration

Les variables d'environnement peuvent être définies dans un fichier .env :

# Database
DB_USER=veza
DB_PASS=password
DB_NAME=veza

# Ports
PORT_GO=8080
PORT_CHAT=3000
PORT_STREAM=3001
PORT_WEB=5173
PORT_HAPROXY=80

# JWT Secret (CHANGEZ EN PRODUCTION!)
JWT_SECRET=your-secret-key-minimum-32-characters

# CORS
CORS_ORIGINS=http://localhost:5173,http://localhost:3000

Troubleshooting

Ports occupés

# Vérifier les ports
make check-ports

Services ne démarrent pas

# Vérifier les logs
make logs-service SERVICE=backend-api

# Vérifier le statut
make status-full

Problèmes avec Incus

# Vérifier que Incus est installé
incus version

# Vérifier les containers
incus list

# Voir les logs d'un container
make incus-logs SERVICE=backend-api

Exemples d'utilisation

Scénario 1 : Développement local

# Setup initial
make setup

# Démarrer l'infrastructure
make infra-up

# Démarrer les services en mode dev
make dev

Scénario 2 : Déploiement Docker

# Builder et déployer
make deploy-docker

# Vérifier le statut
make status-full

# Voir les logs d'un service
make logs-service SERVICE=backend-api

Scénario 3 : Déploiement Incus

# Setup Incus
sudo snap install incus
sudo incus admin init

# Déployer
make deploy-incus

# Vérifier
make status-full

Scénario 4 : Maintenance

# Redémarrer un service spécifique
make restart-service SERVICE=backend-api

# Rebuilder un service
make build-service SERVICE=backend-api
make restart-service SERVICE=backend-api