veza/docs/STAGING_DEPLOYMENT.md

Déploiement Staging — v0.981

Procédure pas-à-pas pour déployer l'environnement staging Veza avec docker-compose.staging.yml et config/caddy/Caddyfile.staging.

---

Prérequis

• Docker et Docker Compose installés
• .env créé à partir de .env.staging.example avec les variables remplies

---

1. Configuration

1.1 Créer le fichier .env

cp .env.staging.example .env
# Éditer .env et remplir toutes les variables requises

Variables obligatoires :

• STAGING_DB_PASSWORD
• STAGING_RABBITMQ_PASSWORD
• STAGING_JWT_SECRET
• STAGING_S3_ACCESS_KEY
• STAGING_S3_SECRET_KEY

Variables optionnelles (valeurs par défaut) :

• STAGING_CORS_ORIGINS (défaut : https://staging.veza.app,https://staging-api.veza.app)
• STAGING_COOKIE_DOMAIN (défaut : .staging.veza.app)

1.2 Staging local (développement)

Pour un déploiement staging local (postgres dans docker sans SSL), configurer :

STAGING_DB_SSLMODE=disable

Si sslmode=require est utilisé et que postgres local n'a pas SSL, la connexion DB échouera avec une erreur du type "connection requires SSL". Voir .env.staging.example.

---

2. Build et démarrage

2.1 Valider la configuration

docker-compose -f docker-compose.staging.yml config

Attendu : validation OK, pas d'erreur de substitution de variables.

2.2 Builder et démarrer

docker-compose -f docker-compose.staging.yml build
docker-compose -f docker-compose.staging.yml up -d

2.3 Appliquer les migrations

Les migrations sont exécutées automatiquement au démarrage du backend. Si vous devez les lancer manuellement (par exemple après une mise à jour du schéma) :

# Depuis la racine du projet
export DATABASE_URL="postgresql://veza:${STAGING_DB_PASSWORD}@localhost:5432/veza_staging?sslmode=${STAGING_DB_SSLMODE:-disable}"
cd veza-backend-api && go run cmd/migrate_tool/main.go

Ou via le conteneur backend :

docker exec veza_backend_staging wget -qO- http://localhost:8080/api/v1/health
# Vérifier que le backend répond (migrations lancées au démarrage)

---

3. Vérification

3.1 Health checks

Backend — health simple :

curl -s http://localhost:8080/api/v1/health | jq .
# Attendu: { "status": "ok" }

Backend — deep health (DB, Redis, RabbitMQ, S3) :

curl -s http://localhost:8080/api/v1/health/deep | jq .
# Attendu: "status": "healthy" (ou "degraded" acceptable pour certains services)

Via Caddy (si accès par port 80/443) :

curl -s http://localhost/api/v1/health/deep | jq .

3.2 Stream server

curl -s http://localhost:3001/health | jq .
# Ou via Caddy: curl -s http://localhost/stream (WebSocket)

3.3 Frontend

• Navigateur : http://localhost (via Caddy) ou http://localhost:5173 (port direct frontend)
• La page de login doit s'afficher

3.4 Services disponibles

Service	Port direct	Via Caddy
Caddy (proxy)	80, 443	-
Backend	8080	/api/*
Stream server	3001	/stream, /hls/*
Frontend	5173	/*
MinIO console	9001	-

---

4. Arrêt et nettoyage

docker-compose -f docker-compose.staging.yml down
# Avec volumes : docker-compose -f docker-compose.staging.yml down -v

---

Références

• docker-compose.staging.yml
• config/caddy/Caddyfile.staging
• SMOKE_TEST_V0981.md — checklist bug bash
• BUG_BASH_V0981.md — suivi des bugs