docs: add deployment guide (chillka, huitral, Docker, Keycloak)

Co-authored-by: Cursor <cursoragent@cursor.com>

1 files changed, 349 insertions, 0 deletions

diff --git a/DEPLOY.md b/DEPLOY.md
new file mode 100644
index 0000000..27369f1
--- /dev/null
+++ b/DEPLOY.md
@@ -0,0 +1,349 @@
+# Deploiement Der-topogo
+
+Guide complet pour la mise en place du repo Git sur chillka et le deploiement sur huitral.
+
+## Architecture
+
+```
+Poste dev (Windows)
+    |
+    | git push
+    v
+chillka (bare repo Git)
+    |
+    | git clone / git pull (ou hook post-receive)
+    v
+huitral (Docker Compose)
+    ├── Caddy (reverse proxy, TLS auto)
+    └── App Next.js + Payload CMS
+            |
+            | connexion PostgreSQL (existant)
+            | connexion Keycloak OIDC (npagnun)
+```
+
+---
+
+## 1. Creer le bare repo sur chillka
+
+```bash
+ssh toshiro@chillka
+
+# Creer le repertoire pour les repos (une seule fois)
+mkdir -p ~/git
+cd ~/git
+
+# Creer le bare repo
+git init --bare der-topogo.git
+
+# Ajouter une description (optionnel)
+echo "Site consulting IAM & Securite - Der-topogo" > ~/git/der-topogo.git/description
+
+exit
+```
+
+## 2. Connecter le repo local a chillka
+
+Depuis le poste de developpement Windows :
+
+```bash
+cd e:\Dev\Web-Works\Der-topogo
+
+# Ajouter chillka comme remote "origin"
+git remote add origin toshiro@chillka:git/der-topogo.git
+
+# Pousser le code (premier push)
+git push -u origin main
+```
+
+Pour les push suivants, un simple `git push` suffit.
+
+## 3. Premier deploiement sur huitral
+
+### 3a. Preparer le serveur
+
+```bash
+ssh toshiro@huitral
+
+# Verifier que Docker et Docker Compose sont installes
+docker --version
+docker compose version
+
+# Creer le dossier applicatif
+mkdir -p ~/apps
+cd ~/apps
+
+# Cloner le repo depuis chillka
+git clone toshiro@chillka:git/der-topogo.git
+cd der-topogo
+```
+
+### 3b. Configurer l'environnement de production
+
+```bash
+# Copier le template
+cp .env.example .env.local
+
+# Editer avec les valeurs de production
+nano .env.local
+```
+
+Valeurs a renseigner dans `.env.local` :
+
+| Variable | Description | Exemple |
+|---|---|---|
+| `DATABASE_URI` | Connexion PostgreSQL | `postgresql://user:pass@pg-host:5432/dertopogo` |
+| `PAYLOAD_SECRET` | Secret Payload CMS (min 32 chars) | Generer avec `openssl rand -hex 32` |
+| `NEXT_PUBLIC_SITE_URL` | URL publique du site | `https://votre-domaine.com` |
+| `KEYCLOAK_ISSUER` | URL du realm Keycloak (npagnun) | `https://npagnun.domain.com/realms/votre-realm` |
+| `KEYCLOAK_CLIENT_ID` | Client ID OIDC | `dertopogo` |
+| `KEYCLOAK_CLIENT_SECRET` | Client Secret OIDC | Depuis la console Keycloak |
+| `AUTH_SECRET` | Secret Auth.js (min 32 chars) | Generer avec `openssl rand -hex 32` |
+| `AUTH_URL` | URL du site (identique a SITE_URL) | `https://votre-domaine.com` |
+
+Pour generer les secrets :
+
+```bash
+# Generer PAYLOAD_SECRET
+openssl rand -hex 32
+
+# Generer AUTH_SECRET
+openssl rand -hex 32
+```
+
+### 3c. Configurer le domaine dans le Caddyfile
+
+```bash
+nano Caddyfile
+```
+
+Remplacer `your-domain.com` par le vrai nom de domaine. Caddy gerera automatiquement le certificat TLS via Let's Encrypt.
+
+### 3d. Construire et lancer
+
+```bash
+docker compose up -d --build
+```
+
+### 3e. Verifier le deploiement
+
+```bash
+# Verifier que les conteneurs tournent
+docker compose ps
+
+# Verifier les logs de l'application
+docker compose logs app
+
+# Verifier les logs de Caddy
+docker compose logs caddy
+
+# Tester l'acces HTTP (depuis huitral)
+curl -I https://votre-domaine.com
+```
+
+Verifications attendues :
+- `docker compose ps` : 2 services "running" (caddy + app)
+- Les headers de securite sont presents (X-Content-Type-Options, X-Frame-Options, etc.)
+- Le site repond en HTTPS avec un certificat valide
+- `/admin` affiche l'interface Payload CMS
+
+---
+
+## 4. Mises a jour
+
+### Workflow standard
+
+Depuis le poste de dev :
+
+```bash
+# Apres avoir commit les changements
+git push origin main
+```
+
+Puis sur huitral :
+
+```bash
+ssh toshiro@huitral
+cd ~/apps/der-topogo
+git pull origin main
+docker compose up -d --build
+```
+
+### Mise a jour sans downtime
+
+Si le build prend du temps et que vous voulez minimiser le downtime :
+
+```bash
+ssh toshiro@huitral
+cd ~/apps/der-topogo
+git pull origin main
+
+# Construire la nouvelle image sans arreter les services
+docker compose build app
+
+# Relancer uniquement le conteneur app
+docker compose up -d --no-deps app
+```
+
+---
+
+## 5. Deploy automatique (hook post-receive)
+
+Pour deployer automatiquement sur huitral a chaque `git push` vers chillka.
+
+### Pre-requis
+
+Chillka doit pouvoir se connecter en SSH a huitral. Tester :
+
+```bash
+ssh toshiro@chillka
+ssh toshiro@huitral echo "OK"
+```
+
+Si ca ne fonctionne pas, generer une cle sur chillka et l'autoriser sur huitral :
+
+```bash
+# Sur chillka
+ssh-keygen -t ed25519 -C "chillka-deploy"
+ssh-copy-id toshiro@huitral
+```
+
+### Creer le hook
+
+```bash
+ssh toshiro@chillka
+
+cat > ~/git/der-topogo.git/hooks/post-receive << 'HOOK'
+#!/bin/bash
+BRANCH=$(git rev-parse --symbolic --abbrev-ref $3)
+
+if [ "$BRANCH" = "main" ]; then
+    echo "==> Push on main detected, deploying to huitral..."
+    ssh toshiro@huitral "cd ~/apps/der-topogo && git pull origin main && docker compose up -d --build"
+    echo "==> Deploy complete."
+else
+    echo "==> Push on branch $BRANCH, skipping deploy."
+fi
+HOOK
+
+chmod +x ~/git/der-topogo.git/hooks/post-receive
+exit
+```
+
+Desormais, chaque `git push origin main` depuis le poste de dev deploiera automatiquement sur huitral.
+
+---
+
+## 6. Rollback
+
+### Revenir au commit precedent
+
+```bash
+ssh toshiro@huitral
+cd ~/apps/der-topogo
+
+# Voir les derniers commits
+git log --oneline -10
+
+# Revenir a un commit specifique
+git checkout <commit-hash>
+
+# Reconstruire
+docker compose up -d --build
+```
+
+### Revenir a la derniere version stable
+
+```bash
+git checkout main
+docker compose up -d --build
+```
+
+---
+
+## 7. Commandes Docker Compose utiles
+
+```bash
+# Voir l'etat des services
+docker compose ps
+
+# Voir les logs en temps reel
+docker compose logs -f
+
+# Logs d'un service specifique
+docker compose logs -f app
+docker compose logs -f caddy
+
+# Redemarrer un service
+docker compose restart app
+
+# Arreter tous les services
+docker compose down
+
+# Arreter et supprimer les volumes (ATTENTION: perte de donnees media)
+docker compose down -v
+
+# Reconstruire sans cache
+docker compose build --no-cache app
+
+# Voir l'utilisation des ressources
+docker compose top
+docker stats
+```
+
+---
+
+## 8. Sauvegarde
+
+### Donnees a sauvegarder
+
+1. **Base PostgreSQL** : contient les donnees Payload CMS (articles, services, users, etc.)
+2. **Volume media** : images et fichiers uploades
+3. **Fichier .env.local** : configuration et secrets
+
+### Sauvegarder les medias
+
+```bash
+# Depuis huitral
+docker compose cp app:/app/media ./backup-media-$(date +%Y%m%d)
+```
+
+### Sauvegarder la base PostgreSQL
+
+```bash
+# Adapter l'hote et les credentials selon votre .env.local
+pg_dump -h pg-host -U user -d dertopogo > backup-db-$(date +%Y%m%d).sql
+```
+
+---
+
+## 9. Configuration Keycloak (npagnun)
+
+Pour connecter le site a votre Keycloak existant, creer un client OIDC dans votre realm :
+
+1. Se connecter a l'admin Keycloak : `https://npagnun.domain.com/admin`
+2. Selectionner le realm
+3. Clients > Create client
+4. Parametres :
+
+| Parametre | Valeur |
+|---|---|
+| Client ID | `dertopogo` |
+| Client Protocol | openid-connect |
+| Client authentication | On (confidential) |
+| Valid Redirect URIs | `https://votre-domaine.com/api/auth/callback/keycloak` |
+| Valid Post Logout Redirect URIs | `https://votre-domaine.com` |
+| Web Origins | `https://votre-domaine.com` |
+
+5. Onglet "Credentials" : copier le Client Secret dans `.env.local` (`KEYCLOAK_CLIENT_SECRET`)
+6. Onglet "Client scopes" > ajouter `roles` au scope par defaut pour inclure les roles dans le token
+
+---
+
+## Resume des serveurs
+
+| Serveur | Role | Acces |
+|---|---|---|
+| **chillka** | Repo Git (bare) | `toshiro@chillka:git/der-topogo.git` |
+| **huitral** | Hebergement Docker | `toshiro@huitral` (apps dans `~/apps/der-topogo`) |
+| **npagnun** | Keycloak (IdP OIDC) | Console admin Keycloak |
+| **PostgreSQL** | Base de donnees | Connexion via `DATABASE_URI` |