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](../docker-compose.staging.yml) et [config/caddy/Caddyfile.staging](../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

```bash
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](../.env.staging.example).

---

## 2. Build et démarrage

### 2.1 Valider la configuration

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

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

### 2.2 Builder et démarrer

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

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

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

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

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

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

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

### 3.2 Stream server

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

```bash
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](../docker-compose.staging.yml)
- [config/caddy/Caddyfile.staging](../config/caddy/Caddyfile.staging)
- [SMOKE_TEST_V0981.md](SMOKE_TEST_V0981.md) — checklist bug bash
- [BUG_BASH_V0981.md](BUG_BASH_V0981.md) — suivi des bugs