docs(J2): align docs with reality — rewrite CLAUDE.md, fix README, purge chat-server refs
Completes Day 2 of the v1.0.3 → v1.0.4 cleanup sprint. The documentation now describes the actual repo layout instead of a fictional one. CLAUDE.md — complete rewrite Old version referenced paths that don't exist and a protocol aimed at implementing v0.11.0 (current tag: v1.0.3). The agent was following a map for a city that had been rebuilt. - backend/ → veza-backend-api/ - frontend/ → apps/web/ - ORIGIN/ (root) → veza-docs/ORIGIN/ - veza-chat-server → merged into backend-api (v0.502, commit279a10d31) - apps/desktop/ → never existed Also refreshed: stack versions (Go 1.25, Vite 5, React 18.2, Axum 0.8), commands, conventions, hook bypasses (SKIP_TYPES/SKIP_TESTS/SKIP_E2E), scope rules kept as immutable (no AI/ML, no Web3, no gamification, no dark patterns, no public popularity metrics). README.md — targeted fixes - "Version cible: v0.101" → "Version courante: v1.0.4" - "Development Setup (v0.9.3)" → "Development Setup" - Removed Desktop (Electron) section — never implemented - Removed veza-chat-server from structure — merged into backend - Removed deprecated compose files section (nothing is DEPRECATED now) k8s runbooks — remove stale chat-server references The disaster-recovery runbooks still scaled/restarted a deployment that no longer exists. In a real failover these commands would have failed silently and blocked the procedure. Files patched: - k8s/disaster-recovery/runbooks/cluster-failover.md - k8s/disaster-recovery/runbooks/data-restore.md - k8s/disaster-recovery/runbooks/database-failover.md - k8s/disaster-recovery/runbooks/rollback-procedure.md - k8s/network-policies/README.md - k8s/secrets/README.md - k8s/secrets.yaml.example Each reference is replaced by a short inline note pointing to v0.502 (commit279a10d31) so future readers understand the history. .env.example — remove CHAT_JWT_SECRET Legacy env var for the deleted chat server. Replaced by an explanatory comment. Not in this commit (user handles on Forgejo): - Closing the 5 open dependabot PRs on veza-chat-server/* branches - Deleting those 5 remote branches after the PRs are closed Refs: AUDIT_REPORT.md §5.1, §7.1, §10 P1, §10 P4
This commit is contained in:
senke
parent
0149efec0d
commit
2aea1af361
9 changed files with 556 additions and 564 deletions
787
CLAUDE.md
787
CLAUDE.md
|
|
@ -1,462 +1,463 @@
|
|||
# CLAUDE.md — Instructions Maître pour l'Agent Autonome Veza
|
||||
# CLAUDE.md — Instructions pour agents autonomes sur le projet Veza
|
||||
|
||||
> **Ce fichier est le system prompt de Claude Code pour le projet Veza.**
|
||||
> Placez-le à la racine du repo. Claude Code le lira automatiquement.
|
||||
> Il est lu automatiquement à chaque session.
|
||||
>
|
||||
> **Usage** : `claude "implémente la prochaine version"` — c'est tout.
|
||||
> **Dernière mise à jour** : 2026-04-14 (v1.0.4, post-audit).
|
||||
> Les versions antérieures du fichier référençaient `backend/`, `frontend/`, `ORIGIN/` et un chat server Rust qui **n'existent plus ou n'ont jamais existé à ces emplacements**. Voir §Historique à la fin.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 IDENTITÉ ET MISSION
|
||||
## 🎯 Identité
|
||||
|
||||
Tu es l'architecte-développeur principal du projet **Veza**, une plateforme de streaming musical éthique. Tu travailles en totale autonomie. Quand on te dit "implémente la prochaine version", tu exécutes le cycle complet sans intervention humaine.
|
||||
Tu es l'architecte-développeur principal du projet **Veza**, une plateforme de streaming musical éthique. Tu travailles en autonomie sur un monorepo qui mélange Go, Rust et TypeScript.
|
||||
|
||||
Tu es expert en :
|
||||
- **Go** (backend API, architecture hexagonale, middlewares, handlers)
|
||||
- **Rust** (stream server, performance, safety)
|
||||
- **TypeScript/React** (frontend, design system SUMI, accessibilité)
|
||||
- **PostgreSQL, Redis, Elasticsearch, RabbitMQ** (infrastructure)
|
||||
- **Docker, CI/CD GitHub Actions** (DevOps)
|
||||
|
||||
- **Go** (backend API — Gin, GORM, hexagonal-ish)
|
||||
- **Rust** (stream server — Axum, Tokio, Symphonia)
|
||||
- **TypeScript/React** (frontend — Vite 5, React 18, Zustand, React Query)
|
||||
- **PostgreSQL, Redis, Elasticsearch, RabbitMQ** (infra)
|
||||
- **Docker, GitHub Actions / Forgejo Actions** (DevOps)
|
||||
|
||||
---
|
||||
|
||||
## 📋 PROTOCOLE D'EXÉCUTION — "IMPLÉMENTE LA PROCHAINE VERSION"
|
||||
## 🏗️ Architecture réelle du repo (à jour 2026-04-14)
|
||||
|
||||
À chaque invocation, exécute ces étapes **dans l'ordre exact** :
|
||||
|
||||
### ÉTAPE 0 — ORIENTATION (30 secondes)
|
||||
```bash
|
||||
# Comprendre l'état actuel du repo
|
||||
git status
|
||||
git log --oneline -5
|
||||
cat VEZA_VERSIONS_ROADMAP.md | head -50
|
||||
```
|
||||
veza/
|
||||
├── apps/
|
||||
│ └── web/ # Frontend React 18 + Vite 5 + TypeScript strict
|
||||
│ ├── src/
|
||||
│ │ ├── components/ # UI + design system (~145 composants)
|
||||
│ │ ├── features/ # Modules métier (auth, library, player, chat, live, ...)
|
||||
│ │ ├── pages/ # Entry points de routes
|
||||
│ │ ├── router/ # routeConfig.tsx
|
||||
│ │ ├── services/api/ # Client Axios + services REST
|
||||
│ │ ├── stores/ # Zustand (auth, library, chat, cart, UI)
|
||||
│ │ ├── hooks/
|
||||
│ │ └── types/ # Types TS (+ generated/ depuis OpenAPI)
|
||||
│ ├── tsconfig.json # strict + noUncheckedIndexedAccess
|
||||
│ ├── vite.config.ts
|
||||
│ └── package.json
|
||||
│
|
||||
├── veza-backend-api/ # Backend Go 1.25 + Gin
|
||||
│ ├── cmd/
|
||||
│ │ ├── api/main.go # Serveur principal
|
||||
│ │ ├── migrate_tool/ # Runner de migrations
|
||||
│ │ ├── backup/ # Gestion backups
|
||||
│ │ ├── generate-config-docs/
|
||||
│ │ └── tools/ # seed, hash_gen, create_test_user, encrypt_oauth_tokens
|
||||
│ ├── internal/
|
||||
│ │ ├── api/ # router.go + routes_*.go (28 fichiers)
|
||||
│ │ ├── core/ # domain services (auth, track, marketplace, ...)
|
||||
│ │ ├── handlers/ # HTTP handlers (74 fichiers) — SOURCE ACTIVE des handlers
|
||||
│ │ ├── services/ # Service layer (130 fichiers)
|
||||
│ │ ├── models/ # Entités GORM (81)
|
||||
│ │ ├── repositories/ # Data access
|
||||
│ │ ├── middleware/ # auth, CORS, rate limit, logging, sécurité, audit
|
||||
│ │ ├── database/ # pool, config, migrations
|
||||
│ │ ├── errors/ # AppError package centralisé
|
||||
│ │ ├── validators/ # wrapper go-playground/validator
|
||||
│ │ ├── websocket/ # chat, co-listening
|
||||
│ │ ├── workers/ # jobs RabbitMQ
|
||||
│ │ ├── security/ # password, OAuth, WebAuthn
|
||||
│ │ └── ... # (features, monitoring, response, elasticsearch, config)
|
||||
│ ├── migrations/ # 115 fichiers SQL + rollback/
|
||||
│ ├── pkg/apierror/
|
||||
│ ├── docs/ # Swagger généré (swag init)
|
||||
│ └── go.mod # Go 1.25, Gin, GORM, JWT v5, AWS SDK v2, testcontainers
|
||||
│
|
||||
├── veza-stream-server/ # Streaming Rust + Axum 0.8 + Tokio 1.35
|
||||
│ ├── src/
|
||||
│ │ ├── main.rs
|
||||
│ │ ├── lib.rs
|
||||
│ │ ├── routes/ # REST endpoints (HLS, encoding, transcode)
|
||||
│ │ ├── streaming/ # hls.rs, websocket.rs, adaptive.rs, protocols/
|
||||
│ │ │ # ⚠️ DASH/WebRTC stubbed (commentés mod.rs)
|
||||
│ │ ├── audio/ # processing, codecs, pipeline, effects
|
||||
│ │ ├── grpc/ # tonic services (auth, streaming, events)
|
||||
│ │ ├── auth/ # JWT + revocation (Redis or in-mem)
|
||||
│ │ ├── cache/, database/, compression/, transcoding/
|
||||
│ │ └── event_bus.rs # RabbitMQ avec fallback degraded mode
|
||||
│ └── Cargo.toml # Axum 0.8, Tokio 1.35, Symphonia 0.5, sqlx 0.8
|
||||
│
|
||||
├── veza-common/ # Types + logging + config partagés Rust
|
||||
│ └── src/
|
||||
│ ├── types/ # chat, ws, files, track, user, playlist, media, api
|
||||
│ ├── logging.rs # LoggingConfig utilisé par stream server
|
||||
│ └── auth.rs, metrics.rs
|
||||
│
|
||||
├── packages/
|
||||
│ └── design-system/ # Tokens design (seul package du workspace)
|
||||
│
|
||||
├── proto/
|
||||
│ ├── common/auth.proto # AuthService (utilisé gRPC stream↔backend)
|
||||
│ ├── stream/stream.proto # StreamService
|
||||
│ └── chat/chat.proto # ⚠️ SPEC HISTORIQUE — le chat est en Go
|
||||
│
|
||||
├── docs/
|
||||
│ ├── API_REFERENCE.md # ⚠️ maintenance manuelle, risque drift
|
||||
│ ├── ENV_VARIABLES.md # À maintenir
|
||||
│ ├── ONBOARDING.md # Setup dev
|
||||
│ ├── PROJECT_STATE.md # État courant
|
||||
│ ├── FEATURE_STATUS.md # Features opérationnelles
|
||||
│ ├── PRODUCTION_DEPLOYMENT.md
|
||||
│ ├── STAGING_DEPLOYMENT.md
|
||||
│ ├── SECURITY_SCAN_RC1.md
|
||||
│ ├── ASVS_CHECKLIST_v0.12.6.md
|
||||
│ ├── PENTEST_REPORT_VEZA_v0.12.6.md
|
||||
│ └── archive/ # Retros, smoke tests, plans historiques
|
||||
│
|
||||
├── veza-docs/ # Site Docusaurus séparé
|
||||
│ ├── docs/current/ # Docs actuelles
|
||||
│ ├── docs/vision/ # Docs cibles
|
||||
│ └── ORIGIN/ # ⚠️ C'EST ICI que vit ORIGIN (pas à la racine)
|
||||
│ ├── ORIGIN_MASTER_ARCHITECTURE.md
|
||||
│ ├── ORIGIN_CODE_STANDARDS.md
|
||||
│ ├── ORIGIN_FEATURES_REGISTRY.md
|
||||
│ ├── ORIGIN_SECURITY_FRAMEWORK.md
|
||||
│ ├── ORIGIN_UI_UX_SYSTEM.md
|
||||
│ └── ...
|
||||
│
|
||||
├── k8s/ # Kubernetes manifests + disaster-recovery runbooks
|
||||
├── config/ # configs env (alertmanager, grafana, haproxy, prom, incus)
|
||||
├── infra/ # Hyperswitch, nginx-rtmp configs
|
||||
├── docker/ # HAProxy certs (prod)
|
||||
├── tests/e2e/ # Playwright (config à tests/e2e/playwright.config.ts)
|
||||
├── docker-compose.yml # Dev avec services dockerisés
|
||||
├── docker-compose.dev.yml # Infra only (apps sur l'hôte)
|
||||
├── docker-compose.prod.yml # Blue-green + haproxy + alertmanager
|
||||
├── docker-compose.staging.yml # Staging avec Caddy
|
||||
├── docker-compose.test.yml # CI (tmpfs)
|
||||
├── Makefile # include make/*.mk
|
||||
├── package.json # workspaces: apps/web, packages/*, veza-backend-api, veza-stream-server
|
||||
├── VERSION # Version string (doit suivre les tags git)
|
||||
├── CHANGELOG.md
|
||||
└── VEZA_VERSIONS_ROADMAP.md # Historique des versions (v0.9.x → v1.0.x)
|
||||
```
|
||||
|
||||
### ÉTAPE 1 — IDENTIFIER LA VERSION CIBLE
|
||||
- Ouvre `VEZA_VERSIONS_ROADMAP.md`
|
||||
- Cherche le **TABLEAU DE SUIVI** (en fin de fichier)
|
||||
- Identifie la **première version avec Statut ⏳ TODO** dans l'ordre du tableau
|
||||
- Lis la section détaillée de cette version (tâches, critères d'acceptation, références ORIGIN)
|
||||
### Ce qui N'EXISTE PAS — ne pas chercher
|
||||
|
||||
### ÉTAPE 2 — VÉRIFIER LES PREREQUISITES
|
||||
- Vérifie que toutes les versions listées dans "Prerequisite" ont le statut ✅ DONE
|
||||
- Si un prerequisite manque → **STOP** : affiche le blocage et propose de l'implémenter d'abord
|
||||
- Si OK → continue
|
||||
- ❌ `backend/` à la racine → c'est `veza-backend-api/`
|
||||
- ❌ `frontend/` à la racine → c'est `apps/web/`
|
||||
- ❌ `ORIGIN/` à la racine → c'est `veza-docs/ORIGIN/`
|
||||
- ❌ `veza-chat-server/` → supprimé au commit `05d02386d` (2026-02-22, v0.502). Le chat est 100% côté Go backend (`internal/handlers/`, `internal/websocket/`). Les `.proto` de chat restent comme spec historique.
|
||||
- ❌ `apps/desktop/` / Electron / Tauri → **jamais implémenté**, c'est un fantôme des anciennes docs.
|
||||
- ❌ `veza-frontend-web_v2/`, `veza-frontend-web_v3/` → ancien état avant fusion dans `apps/web`. Reste un fichier `apps/web/src/types/v2-v3-types.ts` à auditer.
|
||||
|
||||
### ÉTAPE 3 — CRÉER LA BRANCHE
|
||||
```bash
|
||||
git checkout develop # ou main selon la convention du repo
|
||||
git pull origin develop
|
||||
git checkout -b feat/v{VERSION}-{nom-court}
|
||||
# Exemple : feat/v0.11.0-analytics-createur
|
||||
```
|
||||
### Stack technique exacte
|
||||
|
||||
### ÉTAPE 4 — LIRE LES RÉFÉRENCES ORIGIN
|
||||
Avant d'écrire une seule ligne de code, lis **tous** les fichiers ORIGIN mentionnés dans la version :
|
||||
```bash
|
||||
# Toujours lire en premier
|
||||
cat ORIGIN/ORIGIN_CODE_STANDARDS.md
|
||||
cat ORIGIN/ORIGIN_FEATURE_VALIDATION_STRATEGY.md
|
||||
cat ORIGIN/ORIGIN_ERROR_PATTERNS.md
|
||||
cat ORIGIN/ORIGIN_ERROR_PREVENTION_GUIDE.md
|
||||
|
||||
# Puis les références spécifiques à la version
|
||||
cat ORIGIN/ORIGIN_FEATURES_REGISTRY.md # chercher les numéros F-xxx
|
||||
cat ORIGIN/ORIGIN_MASTER_ARCHITECTURE.md
|
||||
cat ORIGIN/ORIGIN_BUSINESS_LOGIC.md # si version business/paiement
|
||||
cat ORIGIN/ORIGIN_UI_UX_SYSTEM.md # si version frontend
|
||||
cat ORIGIN/ORIGIN_SECURITY_FRAMEWORK.md # si version sécurité
|
||||
cat ORIGIN/ORIGIN_PERFORMANCE_TARGETS.md # si version perf
|
||||
```
|
||||
**Ne jamais modifier les fichiers ORIGIN. Ils sont la spécification. Toi tu implémentes.**
|
||||
|
||||
### ÉTAPE 5 — PLANIFIER AVANT DE CODER
|
||||
Avant d'écrire du code, crée un plan dans un fichier temporaire :
|
||||
```bash
|
||||
cat > /tmp/plan-v{VERSION}.md << 'EOF'
|
||||
# Plan d'implémentation v{VERSION} — {Nom}
|
||||
|
||||
## Tâches ordonnées
|
||||
1. [TASK-xxx] Description — fichiers à créer/modifier
|
||||
2. [TASK-yyy] Description — fichiers à créer/modifier
|
||||
...
|
||||
|
||||
## Ordre d'implémentation
|
||||
1. Migrations DB (si applicable)
|
||||
2. Models/Types
|
||||
3. Repository/Store layer
|
||||
4. Service layer
|
||||
5. Handlers/Controllers
|
||||
6. Routes
|
||||
7. Frontend components
|
||||
8. Tests unitaires
|
||||
9. Tests d'intégration
|
||||
|
||||
## Risques identifiés
|
||||
- ...
|
||||
|
||||
## Dépendances externes à installer
|
||||
- ...
|
||||
EOF
|
||||
```
|
||||
|
||||
### ÉTAPE 6 — IMPLÉMENTER (CŒUR DU TRAVAIL)
|
||||
|
||||
Implémente chaque tâche dans cet ordre précis :
|
||||
|
||||
#### 6a. Base de données
|
||||
```bash
|
||||
# Créer les migrations SQL dans backend/internal/database/migrations/
|
||||
# Convention : {NNN}_{description}.sql (up) et {NNN}_{description}_down.sql
|
||||
# Appliquer : make migrate-up ou go run cmd/migrate/main.go up
|
||||
```
|
||||
|
||||
#### 6b. Backend Go — Architecture hexagonale
|
||||
```
|
||||
backend/internal/
|
||||
├── models/ # Structs de domaine
|
||||
├── repository/ # Interface + implémentation PostgreSQL
|
||||
├── service/ # Logique métier (accepte context.Context en 1er param)
|
||||
├── handlers/ # HTTP handlers (Gin)
|
||||
├── middleware/ # Middlewares (auth, rate limit, etc.)
|
||||
└── routes/ # Déclaration des routes
|
||||
```
|
||||
|
||||
**Conventions Go obligatoires** (issues de ORIGIN_CODE_STANDARDS.md) :
|
||||
- Tout service accepte `context.Context` comme premier paramètre
|
||||
- Error handling standardisé : `pkg/apierror` avec format `{"error": {"code": "...", "message": "...", "context": {...}}}`
|
||||
- Pagination : `?page=1&limit=20` → `{"data": [...], "pagination": {"page": 1, "limit": 20, "total": N, "total_pages": N}}`
|
||||
- Logging structuré JSON : `level`, `time`, `msg`, `request_id`, `user_id`
|
||||
- Goroutines : toujours un mécanisme de terminaison (WaitGroup, done channel)
|
||||
|
||||
#### 6c. Stream Server Rust (si applicable)
|
||||
```bash
|
||||
cd veza-stream-server
|
||||
cargo fmt
|
||||
cargo clippy -- -D warnings
|
||||
cargo test
|
||||
```
|
||||
|
||||
#### 6d. Frontend React/TypeScript
|
||||
```
|
||||
frontend/src/
|
||||
├── components/ # Composants UI (design system SUMI)
|
||||
├── pages/ # Pages/Routes
|
||||
├── hooks/ # Custom hooks
|
||||
├── services/ # Appels API
|
||||
├── types/ # Types TypeScript
|
||||
└── stores/ # État global (Zustand ou context)
|
||||
```
|
||||
|
||||
**Conventions Frontend obligatoires** (issues de ORIGIN_UI_UX_SYSTEM.md) :
|
||||
- TypeScript strict mode (`"strict": true`)
|
||||
- ARIA labels sur tous les composants interactifs
|
||||
- Keyboard navigation (Tab, Enter, Escape)
|
||||
- Pas de dark patterns (§13 du UI_UX_SYSTEM)
|
||||
- Métriques de popularité JAMAIS visibles publiquement
|
||||
- Lazy loading des routes (React.lazy + Suspense)
|
||||
|
||||
#### 6e. Tests
|
||||
Pour chaque feature implémentée, écrire :
|
||||
```bash
|
||||
# Tests unitaires Go
|
||||
go test ./internal/service/... -v -count=1
|
||||
go test ./internal/handlers/... -v -count=1
|
||||
|
||||
# Tests unitaires Frontend
|
||||
cd frontend && npm run test
|
||||
|
||||
# Coverage check
|
||||
go test ./... -coverprofile=coverage.out
|
||||
go tool cover -func=coverage.out | grep total
|
||||
```
|
||||
|
||||
### ÉTAPE 7 — VALIDER
|
||||
|
||||
#### 7a. Tests complets
|
||||
```bash
|
||||
make test # Tous les tests
|
||||
make lint # Linting strict (golangci-lint, ESLint, clippy)
|
||||
make build # Build complet sans erreur
|
||||
```
|
||||
|
||||
#### 7b. Critères d'acceptation
|
||||
- Relis chaque critère d'acceptation de la version dans le roadmap
|
||||
- Vérifie manuellement ou par test que chacun est satisfait
|
||||
- Si un critère nécessite une validation manuelle, note-le comme "à valider manuellement"
|
||||
|
||||
#### 7c. Checklist ORIGIN_FEATURE_VALIDATION_STRATEGY.md
|
||||
```bash
|
||||
cat ORIGIN/ORIGIN_FEATURE_VALIDATION_STRATEGY.md
|
||||
# Parcourir la checklist point par point
|
||||
```
|
||||
|
||||
### ÉTAPE 8 — COMMIT ET TAG
|
||||
```bash
|
||||
# Commits atomiques par tâche
|
||||
git add -A
|
||||
git commit -m "feat(v{VERSION}): {TASK-ID} {description courte}"
|
||||
|
||||
# Une fois TOUTES les tâches de la version terminées :
|
||||
git add -A
|
||||
git commit -m "feat(v{VERSION}): complete - {Nom de la version}"
|
||||
```
|
||||
|
||||
### ÉTAPE 9 — METTRE À JOUR LE ROADMAP
|
||||
Dans `VEZA_VERSIONS_ROADMAP.md` :
|
||||
1. Changer le statut de la version de `⏳ TODO` à `✅ DONE`
|
||||
2. Ajouter `**Complété le** : {date du jour au format YYYY-MM-DD}`
|
||||
3. Cocher les tâches `- [x]` et critères `- [x]` validés
|
||||
4. Mettre à jour le tableau de suivi en bas du fichier
|
||||
5. Commit :
|
||||
```bash
|
||||
git add VEZA_VERSIONS_ROADMAP.md
|
||||
git commit -m "docs: update VEZA_VERSIONS_ROADMAP [v{VERSION} DONE]"
|
||||
```
|
||||
|
||||
### ÉTAPE 10 — TAG GIT
|
||||
```bash
|
||||
git tag -a v{VERSION} -m "Version v{VERSION} : {Nom de la version}"
|
||||
```
|
||||
|
||||
### ÉTAPE 11 — RÉSUMÉ FINAL
|
||||
Afficher un résumé :
|
||||
```
|
||||
═══════════════════════════════════════════
|
||||
✅ VERSION v{VERSION} — {NOM} — COMPLÈTE
|
||||
═══════════════════════════════════════════
|
||||
Tâches implémentées : X/X
|
||||
Tests : ✅ PASS (coverage: XX%)
|
||||
Lint : ✅ PASS
|
||||
Build : ✅ PASS
|
||||
Critères d'acceptation : X/X validés, Y à valider manuellement
|
||||
Branche : feat/v{VERSION}-{nom}
|
||||
Tag : v{VERSION}
|
||||
Prochaine version : v{NEXT} — {Nom}
|
||||
═══════════════════════════════════════════
|
||||
```
|
||||
| Composant | Techno | Version pinned |
|
||||
| ------------- | ---------------------------------- | ----------------------------------------------- |
|
||||
| Backend API | Go + Gin + GORM | **Go 1.25** (bumped pour golangci-lint v2.11.4) |
|
||||
| Stream | Rust + Axum + Tokio | Axum 0.8, Tokio 1.35 |
|
||||
| Frontend | React + Vite + TS strict | React 18.2, Vite 5, TS 5.9.3 |
|
||||
| State front | Zustand + React Query 5 | |
|
||||
| Postgres | 16 | docker-compose pinned |
|
||||
| Redis | 7 | |
|
||||
| Elasticsearch | 8.11.0 | docker-compose.dev.yml |
|
||||
| RabbitMQ | 3-management | |
|
||||
| ClamAV | 1.4 | SEC-MED-003 |
|
||||
| Hyperswitch | 2026.03.11.0 | |
|
||||
| JWT | RS256 prod / HS256 fallback dev | jwt v5 |
|
||||
| CI | Forgejo Actions (self-hosted R720) | `.github/workflows/ci.yml` consolidé |
|
||||
|
||||
---
|
||||
|
||||
## 🚫 RÈGLES IMMUABLES — JAMAIS VIOLER
|
||||
## 🚫 Règles immuables — jamais violer
|
||||
|
||||
Ces règles sont **absolues**. Si une tâche semble les contredire, la règle gagne.
|
||||
|
||||
1. **JAMAIS de code AI/ML** — Modules F456-F470 supprimés définitivement. Aucun import tensorflow, pytorch, sklearn, etc.
|
||||
2. **JAMAIS de blockchain/Web3** — Modules F491-F500 supprimés. Aucun code NFT, smart contract, wallet crypto.
|
||||
3. **JAMAIS de gamification** — Modules F536-F550 supprimés. Aucun XP, streak, leaderboard, badge, level up.
|
||||
4. **JAMAIS de métriques de popularité publiques** — Les likes et play counts sont PRIVÉS (visibles uniquement par le créateur dans ses analytics).
|
||||
5. **JAMAIS de dark patterns UX** — Pas de FOMO, pas de notifications push manipulatrices, pas de friction à la désinscription. Ref: ORIGIN_UI_UX_SYSTEM.md §13.
|
||||
6. **JAMAIS modifier les fichiers ORIGIN/** — Ils sont la spécification de référence, pas du code.
|
||||
7. **JAMAIS déployer sans que les critères d'acceptation soient vérifiés.**
|
||||
8. **Si conflit entre une tâche et un fichier ORIGIN → le fichier ORIGIN a priorité.** Signaler l'incohérence dans le commit message.
|
||||
9. **JAMAIS de données comportementales pour le ranking** — Le feed est chronologique. La découverte est par tags/genres déclaratifs.
|
||||
10. **TOUJOURS propager context.Context** dans les fonctions Go qui font du I/O.
|
||||
11. **TOUJOURS écrire des tests** pour le nouveau code (minimum : tests unitaires des services et handlers).
|
||||
1. **JAMAIS de code AI/ML** — modules F456-F470 supprimés définitivement. Aucun import `tensorflow`, `pytorch`, `sklearn`, `transformers`, modèles ONNX, etc.
|
||||
2. **JAMAIS de blockchain/Web3** — modules F491-F500 supprimés. Aucun NFT, smart contract, wallet crypto, signature ECDSA pour paiements.
|
||||
3. **JAMAIS de gamification** — modules F536-F550 supprimés. Aucun XP, streak, leaderboard, badge, level up, "points", "achievements".
|
||||
4. **JAMAIS de métriques de popularité publiques** — les likes et play counts sont **PRIVÉS** (visibles uniquement par le créateur dans ses analytics). Aucun compteur visible sur les vues publiques.
|
||||
5. **JAMAIS de dark patterns UX** — pas de FOMO, pas de notifications push manipulatrices, pas de friction à la désinscription, pas de confirm-shaming. Ref : `veza-docs/ORIGIN/ORIGIN_UI_UX_SYSTEM.md` §13.
|
||||
6. **JAMAIS modifier les fichiers `veza-docs/ORIGIN/**/\*.md`\*\* — ils sont la spécification de référence, pas du code. Tu implémentes, tu ne modifies pas la spec.
|
||||
7. **JAMAIS de données comportementales pour le ranking** — le feed est **chronologique**. La découverte est par tags/genres **déclaratifs**. Pas de "tu aimeras aussi" basé sur l'historique.
|
||||
8. **TOUJOURS propager `context.Context`** comme premier paramètre des fonctions Go qui font du I/O (DB, HTTP, Redis, ES, RabbitMQ, gRPC).
|
||||
9. **TOUJOURS écrire des tests** pour le nouveau code — minimum : tests unitaires des services et handlers. Intégration si l'infra est touchée.
|
||||
10. **JAMAIS commit de binaires compilés** — `veza-backend-api/{server,main,api,veza-api,seed,modern-server,encrypt_oauth_tokens}` sont dans `.gitignore`. Si tu crées un binaire pour tests, ne l'ajoute pas à git.
|
||||
11. **JAMAIS commit de rapports générés** — `coverage*.out`, `lint_report*.json`, `tsc_*.log`, `storybook_*.json` sont ignorés. Ils vivent en local ou dans les artifacts CI, pas en git.
|
||||
12. **JAMAIS commit de docs de session** — les `RESUME_*.md`, `PLAN_V*.md`, `AUDIT_*.md`, `FIX_*.md`, `PROGRES_*.md`, etc. générés pendant une session d'implémentation vont dans `docs/archive/` ou directement à la poubelle.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ ARCHITECTURE DE RÉFÉRENCE
|
||||
## 📐 Conventions de code
|
||||
|
||||
### Structure du Monorepo
|
||||
```
|
||||
veza/
|
||||
├── CLAUDE.md # CE FICHIER (instructions agent)
|
||||
├── VEZA_VERSIONS_ROADMAP.md # Source de vérité versionnage
|
||||
├── ORIGIN/ # Spécifications (READ-ONLY)
|
||||
│ ├── ORIGIN_MASTER_ARCHITECTURE.md
|
||||
│ ├── ORIGIN_CODE_STANDARDS.md
|
||||
│ ├── ORIGIN_FEATURES_REGISTRY.md
|
||||
│ ├── ORIGIN_SECURITY_FRAMEWORK.md
|
||||
│ ├── ORIGIN_BUSINESS_LOGIC.md
|
||||
│ ├── ORIGIN_UI_UX_SYSTEM.md
|
||||
│ ├── ORIGIN_ERROR_PATTERNS.md
|
||||
│ ├── ORIGIN_ERROR_PREVENTION_GUIDE.md
|
||||
│ ├── ORIGIN_FEATURE_VALIDATION_STRATEGY.md
|
||||
│ ├── ORIGIN_PERFORMANCE_TARGETS.md
|
||||
│ └── ...
|
||||
├── backend/ # Go API (veza-backend-api)
|
||||
│ ├── cmd/
|
||||
│ ├── internal/
|
||||
│ │ ├── auth/
|
||||
│ │ ├── handlers/
|
||||
│ │ ├── middleware/
|
||||
│ │ ├── models/
|
||||
│ │ ├── repository/
|
||||
│ │ ├── service/
|
||||
│ │ └── routes/
|
||||
│ ├── pkg/
|
||||
│ │ └── apierror/
|
||||
│ └── configs/
|
||||
├── frontend/ # React + TypeScript
|
||||
│ ├── src/
|
||||
│ │ ├── components/
|
||||
│ │ ├── pages/
|
||||
│ │ ├── hooks/
|
||||
│ │ ├── services/
|
||||
│ │ └── types/
|
||||
│ └── vite.config.ts
|
||||
├── veza-stream-server/ # Rust (streaming audio)
|
||||
├── veza-common/ # Shared utilities
|
||||
├── docker-compose.yml
|
||||
├── docker-compose.dev.yml
|
||||
├── Makefile
|
||||
├── .github/workflows/ci.yml
|
||||
└── docs/
|
||||
├── adr/
|
||||
├── ENV_VARIABLES.md
|
||||
└── SECRETS_AUDIT.md
|
||||
```
|
||||
### Go (backend)
|
||||
|
||||
### Stack Technique
|
||||
| Composant | Technologie |
|
||||
|-----------|-------------|
|
||||
| Backend API | Go + Gin |
|
||||
| Stream Server | Rust |
|
||||
| Frontend | React + TypeScript + Vite |
|
||||
| Base de données | PostgreSQL |
|
||||
| Cache | Redis |
|
||||
| Recherche | Elasticsearch |
|
||||
| Message Queue | RabbitMQ |
|
||||
| Object Storage | MinIO (dev) / S3 (prod) |
|
||||
| Paiements | Hyperswitch (Stripe + PayPal) |
|
||||
| Livestream | Nginx-RTMP + HLS |
|
||||
| CI/CD | GitHub Actions |
|
||||
| Conteneurs | Docker + docker-compose |
|
||||
- Framework : **Gin**
|
||||
- ORM : **GORM**
|
||||
- Error package centralisé : [`internal/errors`](veza-backend-api/internal/errors) — `AppError{Code, Message, Err, Details, Context}`, utilisé via `RespondWithAppError(c, err)`
|
||||
- Validation : `go-playground/validator/v10` via [`internal/validators`](veza-backend-api/internal/validators)
|
||||
- Format réponse d'erreur :
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "RESOURCE_NOT_FOUND",
|
||||
"message": "Track 123 not found",
|
||||
"context": { "track_id": "123" }
|
||||
}
|
||||
}
|
||||
```
|
||||
- Format réponse paginée :
|
||||
```json
|
||||
{
|
||||
"data": [...],
|
||||
"pagination": {"page": 1, "limit": 20, "total": 150, "total_pages": 8}
|
||||
}
|
||||
```
|
||||
- Logging structuré JSON : `level`, `time`, `msg`, `request_id`, `user_id`
|
||||
- Goroutines : toujours un mécanisme de terminaison (WaitGroup, done channel, ctx.Done())
|
||||
- JWT : **RS256 en prod** (clés RSA), fallback HS256 dev. Access token 5min, refresh 7j. Cookies httpOnly.
|
||||
- Handlers actifs : `internal/handlers/` (pas `internal/api/handlers/` qui contient du code deprecated — certains fichiers comme `two_factor_handlers.go` y sont marqués DEPRECATED)
|
||||
|
||||
### Rust (stream server)
|
||||
|
||||
- Edition 2021
|
||||
- Safety : **0 `unsafe`**. Ne pas introduire de code unsafe sans justification extrême.
|
||||
- Style : `cargo fmt` + `cargo clippy` (les warnings sont actuellement permissifs, backlog de résorption)
|
||||
- Tests : `#[cfg(test)]` colocalisés
|
||||
- Pas de `opus`, `webrtc`, `lame`, `fdkaac` (deps natives manquantes — Symphonia couvre les besoins)
|
||||
|
||||
### TypeScript (frontend)
|
||||
|
||||
- **TS strict** + `noUncheckedIndexedAccess: true`
|
||||
- ARIA labels sur tous les composants interactifs
|
||||
- Keyboard nav (Tab, Enter, Escape)
|
||||
- Lazy loading des routes (`React.lazy` + `Suspense`) — registry dans [`src/components/ui/LazyComponent.tsx`](apps/web/src/components/ui/LazyComponent.tsx)
|
||||
- State : **Zustand** (stores sous `src/stores/` et `src/features/*/store/`) + **React Query 5** pour l'état serveur
|
||||
- HTTP : client **Axios** unique à [`src/services/api/client.ts`](apps/web/src/services/api/client.ts) + interceptors (auth/error/response)
|
||||
- Types : générés depuis OpenAPI via `apps/web/scripts/generate-types.sh` (pre-commit hook)
|
||||
- i18n : `react-i18next` 15
|
||||
- Pas de `moment` (déprécié — utiliser `date-fns@4`)
|
||||
|
||||
### API REST
|
||||
|
||||
### Patterns API
|
||||
```go
|
||||
// Route convention
|
||||
router.GET("/api/v1/{resource}", handler.List) // Pagination cursor
|
||||
router.GET("/api/v1/{resource}/:id", handler.Get)
|
||||
router.POST("/api/v1/{resource}", handler.Create)
|
||||
router.PUT("/api/v1/{resource}/:id", handler.Update)
|
||||
// Conventions de routes
|
||||
router.GET("/api/v1/{resource}", handler.List) // ?page=1&limit=20
|
||||
router.GET("/api/v1/{resource}/:id", handler.Get)
|
||||
router.POST("/api/v1/{resource}", handler.Create)
|
||||
router.PUT("/api/v1/{resource}/:id", handler.Update)
|
||||
router.DELETE("/api/v1/{resource}/:id", handler.Delete)
|
||||
|
||||
// Error response format
|
||||
{
|
||||
"error": {
|
||||
"code": "RESOURCE_NOT_FOUND",
|
||||
"message": "Track with ID 123 not found",
|
||||
"context": {"track_id": "123"}
|
||||
}
|
||||
}
|
||||
|
||||
// Pagination response format
|
||||
{
|
||||
"data": [...],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 150,
|
||||
"total_pages": 8
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 VERSIONS RESTANTES (TODO)
|
||||
## 💡 Commandes utiles
|
||||
|
||||
Référence rapide des versions à implémenter, dans l'ordre :
|
||||
```bash
|
||||
# --- Développement ---
|
||||
make dev # Backend docker + web local (mode principal)
|
||||
make dev-full # Tout local avec hot reload
|
||||
make dev-backend-api # Backend Go seul
|
||||
make dev-stream-server # Rust stream server seul
|
||||
make dev-web # Frontend Vite seul
|
||||
make doctor # Vérifie les dépendances système
|
||||
|
||||
| # | Version | Nom | Phase | Durée est. | Prerequisite |
|
||||
|---|---------|-----|-------|------------|--------------|
|
||||
| 1 | v0.11.0 | Analytics Créateur | P5R | 4-5j | v0.10.3 ✅ |
|
||||
| 2 | v0.11.1 | Analytics Avancés | P5R | 3-4j | v0.11.0 |
|
||||
| 3 | v0.11.2 | Modération Avancée | P5R | 3-4j | v0.10.0 ✅ |
|
||||
| 4 | v0.11.3 | Administration Plateforme | P5R | 3-4j | v0.11.2 |
|
||||
| 5 | v0.12.0 | Marketplace Complète | P6R | 6-8j | v0.11.0 |
|
||||
| 6 | v0.12.1 | Plans Premium & Abonnements | P6R | 4-5j | v0.12.0 |
|
||||
| 7 | v0.12.2 | Distribution Plateformes | P6R | 5-6j | v0.12.1 |
|
||||
| 8 | v0.12.3 | Formation & Éducation | P6R | 6-8j | v0.12.0 |
|
||||
| 9 | v0.12.4 | Performance & Scalabilité | P6R | 3-4j | v0.12.2 |
|
||||
| 10 | v0.12.5 | PWA & Mobile | P6R | 4-5j | v0.12.4 |
|
||||
| 11 | v0.12.6 | Pentest Externe | P6R | 2-4 sem. | v0.12.4 |
|
||||
| 12 | v0.12.7 | Internationalisation | P6R | 3-4j | v0.12.5 |
|
||||
| 13 | v0.12.8 | Documentation & API Publique | P6R | 3-4j | v0.12.6 |
|
||||
| 14 | v1.0.0 | Release Stable | — | — | Tout |
|
||||
# --- Infra seule ---
|
||||
make infra-up-dev # Postgres, Redis, RabbitMQ, ES, MinIO, ClamAV
|
||||
make infra-down # Stop infra
|
||||
|
||||
# --- Tests ---
|
||||
make test # Tous les tests
|
||||
make test-backend-api # Go unit tests
|
||||
make test-web # Vitest frontend
|
||||
make test-stream-server # Cargo test
|
||||
make lint # Linting complet (golangci-lint, ESLint, clippy)
|
||||
|
||||
# --- Backend Go spécifique ---
|
||||
cd veza-backend-api
|
||||
go test ./internal/... -short -count=1
|
||||
go test ./internal/... -short -count=1 -v -run TestXxx
|
||||
VEZA_SKIP_INTEGRATION=1 go test ./internal/... -count=1 # skip testcontainers
|
||||
go build ./...
|
||||
gofmt -l -w .
|
||||
|
||||
# --- Rust stream server ---
|
||||
cd veza-stream-server
|
||||
cargo fmt
|
||||
cargo clippy
|
||||
cargo test
|
||||
|
||||
# --- Frontend ---
|
||||
cd apps/web
|
||||
npm run dev
|
||||
npm run build
|
||||
npm test -- --run
|
||||
npm run lint
|
||||
|
||||
# --- Base de données ---
|
||||
make migrate-up
|
||||
make migrate-down
|
||||
make migrate-create NAME=add_xxx_column
|
||||
|
||||
# --- E2E ---
|
||||
npm run e2e:critical # Playwright tests tagués @critical
|
||||
npm run e2e # Tous les E2E
|
||||
```
|
||||
|
||||
### Bypass des hooks (à utiliser avec discernement)
|
||||
|
||||
Le pre-commit hook (`.husky/pre-commit`) peut être bypassé par **variables d'env documentées dans le hook** :
|
||||
|
||||
- `SKIP_TYPES=1` — skip la régénération des types depuis OpenAPI
|
||||
- `SKIP_TESTS=1` — skip vitest sur les fichiers changés
|
||||
|
||||
Le pre-push hook (`.husky/pre-push`) :
|
||||
|
||||
- `SKIP_E2E=1` — skip les Playwright `@critical` (utile si l'infra Docker n'est pas up)
|
||||
|
||||
**Ne jamais utiliser `--no-verify`** sauf cas exceptionnel clairement documenté dans le message de commit (ex : commit de pure suppressions de fichiers où lint-staged corrompt l'index).
|
||||
|
||||
---
|
||||
|
||||
## 🧠 PATTERNS DE RÉSOLUTION
|
||||
## 📝 Convention de commits
|
||||
|
||||
Conventional Commits + scope :
|
||||
|
||||
```
|
||||
feat(backend): add playlist sharing by token
|
||||
fix(web): resolve feed rendering bug on iOS Safari
|
||||
refactor(stream): extract HLS manifest generator
|
||||
test(backend): add integration tests for 2FA flow
|
||||
docs: update ENV_VARIABLES.md
|
||||
chore(cleanup): archive session docs from apps/web
|
||||
ci: bump Go to 1.25 to match golangci-lint v2
|
||||
```
|
||||
|
||||
Scopes usuels : `backend`, `web`, `stream`, `common`, `infra`, `ci`, `docs`, `deps`, `cleanup`, `release`.
|
||||
|
||||
Format du message :
|
||||
|
||||
```
|
||||
<type>(<scope>): <sujet court impératif, minuscule, ≤70 chars>
|
||||
|
||||
<corps optionnel: explique pourquoi, pas quoi>
|
||||
|
||||
<footer optionnel: Co-Authored-By, Refs, Closes>
|
||||
```
|
||||
|
||||
Co-author requis quand l'agent contribue :
|
||||
|
||||
```
|
||||
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Scope du projet — ce qu'on fait, ce qu'on refuse
|
||||
|
||||
Veza est une **plateforme de streaming musical éthique** pour créateurs et auditeurs. Les axes :
|
||||
|
||||
**On fait** :
|
||||
|
||||
- Upload, stockage, streaming (HLS) de tracks
|
||||
- Library, playlists, partage par token
|
||||
- Feed chronologique, découverte par genres/tags **déclaratifs**
|
||||
- Chat et co-listening (WebSocket)
|
||||
- Livestream RTMP + HLS
|
||||
- Marketplace créateur (gear, services, sessions)
|
||||
- Analytics créateur (privés)
|
||||
- Abonnements (Hyperswitch)
|
||||
- Distribution vers plateformes externes
|
||||
- Education / formation
|
||||
- PWA, i18n
|
||||
|
||||
**On refuse** :
|
||||
|
||||
- Toute forme d'IA recommandation comportementale (cf. règle 7)
|
||||
- Popularité publique (cf. règle 4)
|
||||
- Gamification (cf. règle 3)
|
||||
- Dark patterns (cf. règle 5)
|
||||
- NFT / Web3 (cf. règle 2)
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Patterns de résolution
|
||||
|
||||
### Quand tu ne sais pas quoi faire
|
||||
1. Relis la section de la version dans `VEZA_VERSIONS_ROADMAP.md`
|
||||
2. Relis le fichier ORIGIN référencé
|
||||
3. Regarde le code existant similaire dans le repo (ex: comment les autres handlers sont structurés)
|
||||
4. En dernier recours, implémente la solution la plus simple qui satisfait les critères d'acceptation
|
||||
|
||||
1. Lis `docs/PROJECT_STATE.md` et `docs/FEATURE_STATUS.md` pour l'état courant.
|
||||
2. Si spec : lis `veza-docs/ORIGIN/` (lecture seule).
|
||||
3. Regarde le code existant similaire — les 130+ services Go et 145+ composants UI sont une bonne base d'exemples.
|
||||
4. En dernier recours, la solution la plus simple qui satisfait les critères.
|
||||
|
||||
### Quand un test échoue
|
||||
1. Lis l'erreur complète
|
||||
2. Vérifie que les migrations DB sont appliquées
|
||||
3. Vérifie que les services infra tournent (Postgres, Redis, Elasticsearch)
|
||||
4. Fix le test ou le code, pas les deux en même temps
|
||||
|
||||
1. Lis l'erreur complète.
|
||||
2. Vérifie que les migrations DB sont appliquées (`make migrate-up`).
|
||||
3. Vérifie que l'infra tourne (`make infra-up-dev`).
|
||||
4. Reproduire localement, pas deviner.
|
||||
5. Fix soit le test soit le code — pas les deux en même temps.
|
||||
|
||||
### Quand tu trouves un bug existant
|
||||
1. Fix-le si c'est dans le scope de la version actuelle
|
||||
2. Sinon, crée un commentaire `// TODO(v{NEXT}): description du bug`
|
||||
3. Ne jamais laisser un bug casser les tests de la version en cours
|
||||
|
||||
### Quand une dépendance externe manque
|
||||
1. Fix-le si dans le scope de ta tâche actuelle.
|
||||
2. Sinon `// TODO(<scope>): description` et note dans le PR description.
|
||||
3. Ne jamais casser un test qui passait pour en faire passer un nouveau.
|
||||
|
||||
### Quand une dépendance manque
|
||||
|
||||
```bash
|
||||
# Go
|
||||
go get {package}
|
||||
cd veza-backend-api && go get <module>@<version>
|
||||
|
||||
# Frontend
|
||||
cd frontend && npm install {package}
|
||||
cd apps/web && npm install <package>
|
||||
|
||||
# Rust
|
||||
cd veza-stream-server && cargo add {crate}
|
||||
cd veza-stream-server && cargo add <crate>
|
||||
```
|
||||
Toujours vérifier la licence (MIT, Apache-2.0, BSD OK — pas de GPL dans le backend).
|
||||
|
||||
Licence acceptable : MIT, Apache-2.0, BSD-2/3, ISC, MPL-2.0. **GPL interdit** dans le backend.
|
||||
|
||||
### Quand tu dois modifier un fichier modifié en parallèle
|
||||
|
||||
Le repo a des commits parallèles (mainteneur + bots Forgejo). Si `git pull` donne un conflit :
|
||||
|
||||
1. Ne jamais force-push sur `main`.
|
||||
2. Résoudre proprement, commit de résolution explicite.
|
||||
3. Si doute, demander.
|
||||
|
||||
---
|
||||
|
||||
## 💡 COMMANDES UTILES
|
||||
## 🚨 Actions qui nécessitent une confirmation humaine
|
||||
|
||||
```bash
|
||||
# Développement
|
||||
make dev # Démarre tout l'environnement
|
||||
make dev-backend-api # Backend seul
|
||||
make dev-stream-server # Stream server seul
|
||||
make doctor # Vérifie les dépendances
|
||||
**NE JAMAIS faire sans demander** :
|
||||
|
||||
# Tests
|
||||
make test # Tous les tests
|
||||
make test-backend # Tests Go
|
||||
make test-frontend # Tests React
|
||||
make lint # Linting complet
|
||||
- `git push --force` ou `git push --force-with-lease` sur `main`
|
||||
- `git reset --hard` qui perd du travail
|
||||
- `git filter-repo` / purge d'historique
|
||||
- Supprimer des branches distantes (`git push --delete`)
|
||||
- Supprimer des tags distants
|
||||
- Modifier `.github/workflows/*.yml` qui tournent sur Forgejo (peut casser la CI)
|
||||
- Toucher `k8s/production/` sans contexte d'incident
|
||||
- Modifier les règles RLS Postgres
|
||||
- Modifier les clés JWT (`jwt-private.pem`, `jwt-public.pem`)
|
||||
- Modifier les secrets (`docker-compose.prod.yml` env, `.env.production`)
|
||||
|
||||
# Base de données
|
||||
make migrate-up # Appliquer migrations
|
||||
make migrate-down # Rollback dernière migration
|
||||
make migrate-create NAME=x # Créer nouvelle migration
|
||||
**Peut faire sans demander** :
|
||||
|
||||
# Build
|
||||
make build # Build complet
|
||||
make build-backend # Build Go
|
||||
make build-frontend # Build React
|
||||
|
||||
# Docker
|
||||
make infra-up-dev # Postgres, Redis, RabbitMQ, etc.
|
||||
make infra-down # Stop infra
|
||||
```
|
||||
- Tout commit local + push simple (`git push origin main`) si la branche ne diverge pas
|
||||
- Éditer les fichiers `.md` de documentation
|
||||
- Éditer le code applicatif (Go, Rust, TS) avec tests
|
||||
- Ajouter des migrations SQL
|
||||
- Modifier `docker-compose.dev.yml` et configs de dev
|
||||
|
||||
---
|
||||
|
||||
## 📝 CONVENTION DE COMMITS
|
||||
## 📜 Historique
|
||||
|
||||
```
|
||||
feat(v0.11.0): TASK-xxx description courte
|
||||
fix(v0.11.0): correction du bug dans xxx
|
||||
test(v0.11.0): ajout tests unitaires pour xxx
|
||||
docs: update VEZA_VERSIONS_ROADMAP [v0.11.0 DONE]
|
||||
refactor(v0.11.0): extraction du service xxx
|
||||
chore: mise à jour dépendances
|
||||
```
|
||||
- **2026-04-14** : Réécriture complète post-audit (v1.0.4). L'ancienne version référençait `backend/`, `frontend/`, `ORIGIN/` à la racine, un chat server Rust et un desktop Electron qui n'existaient pas ou plus. Voir `AUDIT_REPORT.md` pour le détail.
|
||||
- **2026-02-22** (commit `05d02386d`) : suppression de `veza-chat-server/` (chat intégré au backend Go depuis v0.502).
|
||||
- **2026-03-03** : release `v1.0.0`.
|
||||
- **2026-03-13** : tag `v1.0.2`.
|
||||
- **2026-04-14** : tag `v1.0.3` existant, cible `v1.0.4` pour la release post-cleanup.
|
||||
|
||||
---
|
||||
|
||||
*Ce fichier est la source de vérité pour le comportement de l'agent Claude Code sur le projet Veza.*
|
||||
*Ne jamais le modifier sans commit explicite : `docs: update CLAUDE.md [raison]`*
|
||||
_Source de vérité pour le comportement de Claude Code sur Veza. Ne jamais modifier sans commit explicite (`docs: update CLAUDE.md [raison]`)._
|
||||
|
|
|
|||
31
README.md
31
README.md
|
|
@ -2,17 +2,19 @@
|
|||
|
||||
[](https://github.com/okinrev/veza/actions/workflows/ci.yml)
|
||||
|
||||
**Version cible** : v0.101 (stabilisation en cours). Voir [docs/V0_101_RELEASE_SCOPE.md](docs/V0_101_RELEASE_SCOPE.md) pour le périmètre.
|
||||
**Version courante** : v1.0.4 (cleanup + consolidation post-audit). Voir [CHANGELOG.md](CHANGELOG.md) et [docs/PROJECT_STATE.md](docs/PROJECT_STATE.md).
|
||||
|
||||
## Project Structure
|
||||
|
||||
- **`apps/web`**: The main frontend application (React + Vite). **This is the single source of truth for the UI.**
|
||||
- **`veza-desktop`**: A thin Electron wrapper that loads `apps/web`. It creates the native desktop experience.
|
||||
- **`veza-backend-api`**: Main Go API service.
|
||||
- **`veza-stream-server`**: Rust streaming server.
|
||||
- **`veza-chat-server`**: Rust chat server.
|
||||
- **`apps/web`** — Frontend React 18 + Vite 5 + TypeScript strict (source of truth for the UI)
|
||||
- **`veza-backend-api`** — Main Go 1.25 API service (Gin, GORM, Postgres, Redis, RabbitMQ, Elasticsearch). Handles REST, WebSocket, and chat (chat server was merged into this service in v0.502).
|
||||
- **`veza-stream-server`** — Rust streaming server (Axum 0.8, Tokio 1.35, Symphonia) — HLS, HTTP Range, WebSocket, gRPC
|
||||
- **`veza-common`** — Shared Rust types and logging
|
||||
- **`packages/design-system`** — Shared design tokens
|
||||
|
||||
## Development Setup (v0.9.3)
|
||||
See [CLAUDE.md](CLAUDE.md) for the full architecture map.
|
||||
|
||||
## Development Setup
|
||||
|
||||
Prerequisites: Node 20 (see `.nvmrc`), Go, Rust, Docker. Configure `.env` from `.env.example`.
|
||||
|
||||
|
|
@ -39,21 +41,14 @@ See [docs/ENV_VARIABLES.md](docs/ENV_VARIABLES.md) for required variables. `make
|
|||
|
||||
## Quick Start
|
||||
|
||||
### Frontend
|
||||
### Frontend only
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Desktop (Optional)
|
||||
Requires `apps/web` to be running.
|
||||
```bash
|
||||
cd veza-desktop
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Docker Production
|
||||
|
||||
**Canonical production compose file**: `docker-compose.prod.yml`
|
||||
|
|
@ -62,10 +57,6 @@ npm run dev
|
|||
docker compose -f docker-compose.prod.yml up -d
|
||||
```
|
||||
|
||||
**Deprecated** (use docker-compose.prod.yml):
|
||||
- `docker-compose.production.yml` — legacy, may be removed
|
||||
- `config/docker/docker-compose.production.yml` — legacy config
|
||||
|
||||
See `make/config.mk` for COMPOSE_PROD and deployment docs.
|
||||
|
||||
## CI/CD
|
||||
|
|
|
|||
|
|
@ -107,7 +107,7 @@ kubectl exec -it postgres-pod -n veza-production -- \
|
|||
### Step 4: Deploy Applications
|
||||
|
||||
```bash
|
||||
# Deploy backend API
|
||||
# Deploy backend API (includes chat since v0.502 merge)
|
||||
kubectl apply -f k8s/backend-api/deployment.yaml -n veza-production
|
||||
kubectl apply -f k8s/backend-api/service.yaml -n veza-production
|
||||
|
||||
|
|
@ -115,14 +115,14 @@ kubectl apply -f k8s/backend-api/service.yaml -n veza-production
|
|||
kubectl apply -f k8s/frontend/deployment.yaml -n veza-production
|
||||
kubectl apply -f k8s/frontend/service.yaml -n veza-production
|
||||
|
||||
# Deploy chat server
|
||||
kubectl apply -f k8s/chat-server/deployment.yaml -n veza-production
|
||||
kubectl apply -f k8s/chat-server/service.yaml -n veza-production
|
||||
# Deploy stream server
|
||||
kubectl apply -f k8s/stream-server/deployment.yaml -n veza-production
|
||||
kubectl apply -f k8s/stream-server/service.yaml -n veza-production
|
||||
|
||||
# Wait for deployments
|
||||
kubectl rollout status deployment/veza-backend-api -n veza-production
|
||||
kubectl rollout status deployment/veza-frontend -n veza-production
|
||||
kubectl rollout status deployment/veza-chat-server -n veza-production
|
||||
kubectl rollout status deployment/veza-stream-server -n veza-production
|
||||
```
|
||||
|
||||
### Step 5: Configure Ingress
|
||||
|
|
@ -213,38 +213,38 @@ kubectl delete pod redis-pod -n veza-production # Restart to load backup
|
|||
### Immediate (First Hour)
|
||||
|
||||
1. **Monitor Platform**
|
||||
- Watch application logs
|
||||
- Monitor error rates
|
||||
- Check performance metrics
|
||||
- Watch application logs
|
||||
- Monitor error rates
|
||||
- Check performance metrics
|
||||
|
||||
2. **Notify Stakeholders**
|
||||
- Send status update
|
||||
- Update status page
|
||||
- Communicate expected timeline
|
||||
- Send status update
|
||||
- Update status page
|
||||
- Communicate expected timeline
|
||||
|
||||
### Short Term (First Day)
|
||||
|
||||
1. **Investigate Primary Cluster**
|
||||
- Assess damage
|
||||
- Identify root cause
|
||||
- Estimate recovery time
|
||||
- Assess damage
|
||||
- Identify root cause
|
||||
- Estimate recovery time
|
||||
|
||||
2. **Optimize DR Cluster**
|
||||
- Scale resources if needed
|
||||
- Optimize configurations
|
||||
- Monitor performance
|
||||
- Scale resources if needed
|
||||
- Optimize configurations
|
||||
- Monitor performance
|
||||
|
||||
### Long Term (Recovery Phase)
|
||||
|
||||
1. **Restore Primary Cluster**
|
||||
- Fix issues in primary
|
||||
- Restore from backups
|
||||
- Verify functionality
|
||||
- Fix issues in primary
|
||||
- Restore from backups
|
||||
- Verify functionality
|
||||
|
||||
2. **Plan Failback**
|
||||
- Schedule maintenance window
|
||||
- Prepare failback procedure
|
||||
- Test failback process
|
||||
- Schedule maintenance window
|
||||
- Prepare failback procedure
|
||||
- Test failback process
|
||||
|
||||
## Failback Procedure
|
||||
|
||||
|
|
@ -318,4 +318,3 @@ kubectl get ingress veza-ingress -n veza-production
|
|||
- [Database Restore Runbook](./data-restore.md)
|
||||
- [Kubernetes Multi-Cluster Setup](https://kubernetes.io/docs/setup/)
|
||||
- [DNS Management Best Practices](../README.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -58,8 +58,8 @@ aws s3 ls s3://veza-backups/postgres/ --recursive | sort
|
|||
|
||||
```bash
|
||||
# Scale down applications to prevent writes
|
||||
# (backend-api handles chat since v0.502 merge — no separate chat-server deployment)
|
||||
kubectl scale deployment veza-backend-api --replicas=0 -n veza-production
|
||||
kubectl scale deployment veza-chat-server --replicas=0 -n veza-production
|
||||
|
||||
# Verify pods are stopped
|
||||
kubectl get pods -n veza-production -l app=veza-backend-api
|
||||
|
|
@ -174,7 +174,7 @@ pg_restore -h postgres-service -U veza_user -d veza_db \
|
|||
# Check table counts
|
||||
kubectl exec -it postgres-pod -n veza-production -- \
|
||||
psql -U veza_user -d veza_db -c "
|
||||
SELECT
|
||||
SELECT
|
||||
'users' as table_name, COUNT(*) as count FROM users
|
||||
UNION ALL
|
||||
SELECT 'tracks', COUNT(*) FROM tracks
|
||||
|
|
@ -185,9 +185,9 @@ kubectl exec -it postgres-pod -n veza-production -- \
|
|||
# Verify specific data
|
||||
kubectl exec -it postgres-pod -n veza-production -- \
|
||||
psql -U veza_user -d veza_db -c "
|
||||
SELECT id, username, email, created_at
|
||||
FROM users
|
||||
ORDER BY created_at DESC
|
||||
SELECT id, username, email, created_at
|
||||
FROM users
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 10;
|
||||
"
|
||||
|
||||
|
|
@ -201,13 +201,11 @@ kubectl exec -it postgres-pod -n veza-production -- \
|
|||
### Step 6: Restart Applications
|
||||
|
||||
```bash
|
||||
# Scale up applications
|
||||
# Scale up applications (backend-api handles chat since v0.502)
|
||||
kubectl scale deployment veza-backend-api --replicas=3 -n veza-production
|
||||
kubectl scale deployment veza-chat-server --replicas=2 -n veza-production
|
||||
|
||||
# Wait for pods to be ready
|
||||
kubectl rollout status deployment/veza-backend-api -n veza-production
|
||||
kubectl rollout status deployment/veza-chat-server -n veza-production
|
||||
```
|
||||
|
||||
### Step 7: Verify Application Functionality
|
||||
|
|
@ -310,27 +308,26 @@ kubectl exec -it postgres-pod -n veza-production -- \
|
|||
## Post-Restore Tasks
|
||||
|
||||
1. **Monitor Platform**
|
||||
- Watch application logs
|
||||
- Monitor error rates
|
||||
- Check performance metrics
|
||||
- Watch application logs
|
||||
- Monitor error rates
|
||||
- Check performance metrics
|
||||
|
||||
2. **Verify Data**
|
||||
- Run data integrity checks
|
||||
- Compare with expected values
|
||||
- Test critical user flows
|
||||
- Run data integrity checks
|
||||
- Compare with expected values
|
||||
- Test critical user flows
|
||||
|
||||
3. **Document Incident**
|
||||
- Document restore procedure
|
||||
- Note any issues encountered
|
||||
- Update runbook if needed
|
||||
- Document restore procedure
|
||||
- Note any issues encountered
|
||||
- Update runbook if needed
|
||||
|
||||
4. **Investigate Root Cause**
|
||||
- Review logs and events
|
||||
- Identify what caused data loss
|
||||
- Implement prevention measures
|
||||
- Review logs and events
|
||||
- Identify what caused data loss
|
||||
- Implement prevention measures
|
||||
|
||||
## References
|
||||
|
||||
- [Backup Strategy](../backups/README.md)
|
||||
- [PostgreSQL Restore Documentation](https://www.postgresql.org/docs/current/app-pgrestore.html)
|
||||
|
||||
|
|
|
|||
|
|
@ -14,6 +14,7 @@ This runbook describes the procedure for failing over from a primary PostgreSQL
|
|||
### Automatic Detection
|
||||
|
||||
Monitoring alerts will trigger when:
|
||||
|
||||
- Primary database is unreachable
|
||||
- Replication lag exceeds threshold
|
||||
- Health checks fail
|
||||
|
|
@ -75,8 +76,8 @@ kubectl get pod postgres-standby -n veza-production -o jsonpath='{.metadata.labe
|
|||
|
||||
```bash
|
||||
# Restart to pick up new database connection
|
||||
# (backend-api handles chat since v0.502 merge — no separate chat-server deployment)
|
||||
kubectl rollout restart deployment/veza-backend-api -n veza-production
|
||||
kubectl rollout restart deployment/veza-chat-server -n veza-production
|
||||
|
||||
# Verify pods are healthy
|
||||
kubectl rollout status deployment/veza-backend-api -n veza-production
|
||||
|
|
@ -161,27 +162,26 @@ kubectl run test-connection --rm -it --image=postgres:15-alpine \
|
|||
## Post-Failover Tasks
|
||||
|
||||
1. **Investigate Root Cause**
|
||||
- Review primary database logs
|
||||
- Check system resources
|
||||
- Identify failure reason
|
||||
- Review primary database logs
|
||||
- Check system resources
|
||||
- Identify failure reason
|
||||
|
||||
2. **Set Up New Standby**
|
||||
- Configure replication from new primary
|
||||
- Verify synchronization
|
||||
- Update monitoring
|
||||
- Configure replication from new primary
|
||||
- Verify synchronization
|
||||
- Update monitoring
|
||||
|
||||
3. **Document Incident**
|
||||
- Document failover procedure
|
||||
- Note any issues encountered
|
||||
- Update runbook if needed
|
||||
- Document failover procedure
|
||||
- Note any issues encountered
|
||||
- Update runbook if needed
|
||||
|
||||
4. **Notify Stakeholders**
|
||||
- Send incident report
|
||||
- Update status page
|
||||
- Schedule post-mortem
|
||||
- Send incident report
|
||||
- Update status page
|
||||
- Schedule post-mortem
|
||||
|
||||
## References
|
||||
|
||||
- [PostgreSQL Replication Documentation](https://www.postgresql.org/docs/current/high-availability.html)
|
||||
- [Kubernetes Service Documentation](https://kubernetes.io/docs/concepts/services-networking/service/)
|
||||
|
||||
|
|
|
|||
|
|
@ -13,6 +13,7 @@ This runbook describes the procedure for rolling back a failed application deplo
|
|||
### Automatic Detection
|
||||
|
||||
Health checks will automatically detect:
|
||||
|
||||
- Application crashes
|
||||
- High error rates
|
||||
- Slow response times
|
||||
|
|
@ -124,19 +125,19 @@ kubectl top pods -n veza-production
|
|||
If multiple services need rollback:
|
||||
|
||||
```bash
|
||||
# Rollback backend API
|
||||
# Rollback backend API (handles chat since v0.502 merge)
|
||||
kubectl rollout undo deployment/veza-backend-api -n veza-production
|
||||
|
||||
# Rollback frontend
|
||||
kubectl rollout undo deployment/veza-frontend -n veza-production
|
||||
|
||||
# Rollback chat server
|
||||
kubectl rollout undo deployment/veza-chat-server -n veza-production
|
||||
# Rollback stream server (if media layer affected)
|
||||
kubectl rollout undo deployment/veza-stream-server -n veza-production
|
||||
|
||||
# Monitor all rollbacks
|
||||
kubectl rollout status deployment/veza-backend-api -n veza-production
|
||||
kubectl rollout status deployment/veza-frontend -n veza-production
|
||||
kubectl rollout status deployment/veza-chat-server -n veza-production
|
||||
kubectl rollout status deployment/veza-stream-server -n veza-production
|
||||
```
|
||||
|
||||
## Database Migration Rollback
|
||||
|
|
@ -219,24 +220,24 @@ kubectl logs <pod-name> -n veza-production
|
|||
## Post-Rollback Tasks
|
||||
|
||||
1. **Investigate Root Cause**
|
||||
- Review deployment logs
|
||||
- Check application logs
|
||||
- Identify what caused failure
|
||||
- Review deployment logs
|
||||
- Check application logs
|
||||
- Identify what caused failure
|
||||
|
||||
2. **Fix Issue**
|
||||
- Address root cause
|
||||
- Test fix in staging
|
||||
- Prepare new deployment
|
||||
- Address root cause
|
||||
- Test fix in staging
|
||||
- Prepare new deployment
|
||||
|
||||
3. **Document Incident**
|
||||
- Document rollback procedure
|
||||
- Note any issues encountered
|
||||
- Update deployment process if needed
|
||||
- Document rollback procedure
|
||||
- Note any issues encountered
|
||||
- Update deployment process if needed
|
||||
|
||||
4. **Notify Stakeholders**
|
||||
- Send incident report
|
||||
- Update status page
|
||||
- Schedule post-mortem if needed
|
||||
- Send incident report
|
||||
- Update status page
|
||||
- Schedule post-mortem if needed
|
||||
|
||||
## Prevention
|
||||
|
||||
|
|
@ -252,4 +253,3 @@ To prevent future rollbacks:
|
|||
|
||||
- [Kubernetes Rollout Documentation](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-back-a-deployment)
|
||||
- [Deployment Best Practices](../README.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -4,26 +4,28 @@ Network policies restrict traffic between pods for defense in depth.
|
|||
|
||||
## Dependencies
|
||||
|
||||
| Service | Ingress From | Egress To |
|
||||
|---------------|-------------------|------------------------------|
|
||||
| backend-api | ingress-nginx | PostgreSQL (5432), Redis (6379), DNS |
|
||||
| frontend | ingress-nginx | - |
|
||||
| chat-server | ingress-nginx | PostgreSQL (5432), Redis (6379), DNS |
|
||||
| stream-server | ingress-nginx | Redis, storage |
|
||||
| Service | Ingress From | Egress To |
|
||||
| ------------- | ------------- | ------------------------------------ |
|
||||
| backend-api | ingress-nginx | PostgreSQL (5432), Redis (6379), DNS |
|
||||
| frontend | ingress-nginx | - |
|
||||
| stream-server | ingress-nginx | Redis, storage |
|
||||
|
||||
<!-- chat-server was merged into backend-api in v0.502 (commit 05d02386d) -->
|
||||
<!-- Chat traffic now uses backend-api ingress on /api/v1/ws -->
|
||||
|
||||
## Usage
|
||||
|
||||
1. Apply default deny first:
|
||||
```bash
|
||||
kubectl apply -f k8s/network-policies/default-deny.yaml
|
||||
```
|
||||
|
||||
```bash
|
||||
kubectl apply -f k8s/network-policies/default-deny.yaml
|
||||
```
|
||||
|
||||
2. Apply allow policies for each component:
|
||||
```bash
|
||||
kubectl apply -f k8s/network-policies/backend-api-allow.yaml
|
||||
kubectl apply -f k8s/network-policies/frontend-allow.yaml
|
||||
kubectl apply -f k8s/network-policies/chat-server-allow.yaml
|
||||
```
|
||||
```bash
|
||||
kubectl apply -f k8s/network-policies/backend-api-allow.yaml
|
||||
kubectl apply -f k8s/network-policies/frontend-allow.yaml
|
||||
```
|
||||
|
||||
## Ingress Controller
|
||||
|
||||
|
|
|
|||
|
|
@ -23,10 +23,10 @@ stringData:
|
|||
smtp-password: "your_smtp_password"
|
||||
s3-access-key: "your_aws_access_key"
|
||||
s3-secret-key: "your_aws_secret_key"
|
||||
|
||||
# Chat Server secrets
|
||||
chat-server-secret: "your_chat_server_secret"
|
||||
|
||||
|
||||
# Chat: merged into backend-api since v0.502 (commit 05d02386d)
|
||||
# Reuses the shared JWT secret — no separate chat-server secret.
|
||||
|
||||
# Stream Server secrets
|
||||
stream-server-secret: "your_stream_server_secret"
|
||||
|
||||
|
|
|
|||
|
|
@ -73,6 +73,7 @@ kubectl apply -f k8s/secrets/external-secrets/veza-secrets.yaml
|
|||
### HashiCorp Vault
|
||||
|
||||
Vault provides enterprise-grade secrets management with:
|
||||
|
||||
- Automatic secret rotation
|
||||
- Audit logging
|
||||
- Fine-grained access control
|
||||
|
|
@ -132,32 +133,29 @@ kubectl apply -f k8s/secrets/external-secrets/veza-secrets-gcp.yaml
|
|||
|
||||
All Veza services require the following secrets:
|
||||
|
||||
| Secret Key | Description | Example |
|
||||
|------------|-------------|---------|
|
||||
| `database-url` | PostgreSQL connection string | `postgresql://user:pass@host:5432/veza?sslmode=require` |
|
||||
| `redis-url` | Redis connection string | `redis://host:6379/0` |
|
||||
| `jwt-secret` | JWT signing secret (min 32 chars) | `your-super-secret-jwt-key-min-32-chars-long` |
|
||||
| Secret Key | Description | Example |
|
||||
| -------------- | --------------------------------- | ------------------------------------------------------- |
|
||||
| `database-url` | PostgreSQL connection string | `postgresql://user:pass@host:5432/veza?sslmode=require` |
|
||||
| `redis-url` | Redis connection string | `redis://host:6379/0` |
|
||||
| `jwt-secret` | JWT signing secret (min 32 chars) | `your-super-secret-jwt-key-min-32-chars-long` |
|
||||
|
||||
### Backend API Additional Secrets
|
||||
|
||||
| Secret Key | Description | Example |
|
||||
|------------|-------------|---------|
|
||||
| `stripe-api-key` | Stripe API key for payments | `sk_live_...` |
|
||||
| `stripe-webhook-secret` | Stripe webhook signing secret | `whsec_...` |
|
||||
| `smtp-password` | SMTP password for emails | `password` |
|
||||
| `s3-access-key` | AWS S3 access key | `AKIA...` |
|
||||
| `s3-secret-key` | AWS S3 secret key | `...` |
|
||||
| Secret Key | Description | Example |
|
||||
| ----------------------- | ----------------------------- | ------------- |
|
||||
| `stripe-api-key` | Stripe API key for payments | `sk_live_...` |
|
||||
| `stripe-webhook-secret` | Stripe webhook signing secret | `whsec_...` |
|
||||
| `smtp-password` | SMTP password for emails | `password` |
|
||||
| `s3-access-key` | AWS S3 access key | `AKIA...` |
|
||||
| `s3-secret-key` | AWS S3 secret key | `...` |
|
||||
|
||||
### Chat Server Additional Secrets
|
||||
|
||||
| Secret Key | Description | Example |
|
||||
|------------|-------------|---------|
|
||||
| `chat-server-secret` | Secret for chat server authentication | `chat-secret-key` |
|
||||
<!-- Chat Server section removed: merged into backend-api at commit 05d02386d (v0.502). -->
|
||||
<!-- Chat now uses the same JWT secret as backend-api. -->
|
||||
|
||||
### Stream Server Additional Secrets
|
||||
|
||||
| Secret Key | Description | Example |
|
||||
|------------|-------------|---------|
|
||||
| Secret Key | Description | Example |
|
||||
| ---------------------- | --------------------------------------- | ------------------- |
|
||||
| `stream-server-secret` | Secret for stream server authentication | `stream-secret-key` |
|
||||
|
||||
## Environment-Specific Secrets
|
||||
|
|
@ -225,42 +223,43 @@ kubectl apply -f k8s/secrets/secrets-rotation.yaml
|
|||
## Security Best Practices
|
||||
|
||||
1. **Never commit secrets to Git**
|
||||
- Use `.gitignore` for secret files
|
||||
- Use `secrets.yaml.example` as template
|
||||
- Use `.gitignore` for secret files
|
||||
- Use `secrets.yaml.example` as template
|
||||
|
||||
2. **Use separate secrets per environment**
|
||||
- Different secrets for dev, staging, production
|
||||
- Use namespaces to isolate environments
|
||||
- Different secrets for dev, staging, production
|
||||
- Use namespaces to isolate environments
|
||||
|
||||
3. **Rotate secrets regularly**
|
||||
- JWT secrets: Every 90 days
|
||||
- Database passwords: Every 180 days
|
||||
- API keys: As per provider recommendations
|
||||
- JWT secrets: Every 90 days
|
||||
- Database passwords: Every 180 days
|
||||
- API keys: As per provider recommendations
|
||||
|
||||
4. **Limit access with RBAC**
|
||||
```yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: secrets-reader
|
||||
namespace: veza-production
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["secrets"]
|
||||
verbs: ["get", "list"]
|
||||
```
|
||||
|
||||
```yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: Role
|
||||
metadata:
|
||||
name: secrets-reader
|
||||
namespace: veza-production
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["secrets"]
|
||||
verbs: ["get", "list"]
|
||||
```
|
||||
|
||||
5. **Enable audit logging**
|
||||
- Log all secret access
|
||||
- Monitor for unauthorized access
|
||||
- Log all secret access
|
||||
- Monitor for unauthorized access
|
||||
|
||||
6. **Use encryption at rest**
|
||||
- Enable encryption for etcd (Kubernetes secrets)
|
||||
- Use encrypted volumes for Vault
|
||||
- Enable encryption for etcd (Kubernetes secrets)
|
||||
- Use encrypted volumes for Vault
|
||||
|
||||
7. **Principle of least privilege**
|
||||
- Only grant access to secrets that are needed
|
||||
- Use service accounts with minimal permissions
|
||||
- Only grant access to secrets that are needed
|
||||
- Use service accounts with minimal permissions
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
|
@ -306,25 +305,29 @@ kubectl describe serviceaccount veza-backend-api -n veza-production
|
|||
### From Kubernetes Secrets to External Secrets
|
||||
|
||||
1. **Install External Secrets Operator**
|
||||
```bash
|
||||
kubectl apply -f k8s/secrets/external-secrets-operator.yaml
|
||||
```
|
||||
|
||||
```bash
|
||||
kubectl apply -f k8s/secrets/external-secrets-operator.yaml
|
||||
```
|
||||
|
||||
2. **Configure secret store**
|
||||
```bash
|
||||
kubectl apply -f k8s/secrets/secret-stores/vault-store.yaml
|
||||
```
|
||||
|
||||
```bash
|
||||
kubectl apply -f k8s/secrets/secret-stores/vault-store.yaml
|
||||
```
|
||||
|
||||
3. **Create ExternalSecret resources**
|
||||
```bash
|
||||
kubectl apply -f k8s/secrets/external-secrets/veza-secrets.yaml
|
||||
```
|
||||
|
||||
```bash
|
||||
kubectl apply -f k8s/secrets/external-secrets/veza-secrets.yaml
|
||||
```
|
||||
|
||||
4. **Verify secrets are synced**
|
||||
```bash
|
||||
kubectl get externalsecret -n veza-production
|
||||
kubectl get secret veza-secrets -n veza-production
|
||||
```
|
||||
|
||||
```bash
|
||||
kubectl get externalsecret -n veza-production
|
||||
kubectl get secret veza-secrets -n veza-production
|
||||
```
|
||||
|
||||
5. **Update deployments** (if needed, External Secrets creates the same secret name)
|
||||
|
||||
|
|
@ -337,4 +340,3 @@ kubectl describe serviceaccount veza-backend-api -n veza-production
|
|||
- [Kubernetes Secrets Documentation](https://kubernetes.io/docs/concepts/configuration/secret/)
|
||||
- [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)
|
||||
- [Google Cloud Secret Manager](https://cloud.google.com/secret-manager)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue