# Déploiement automatique : Gitea + Docker sur Synology NAS

Ce dépôt contient un **`Dockerfile`** et un **`docker-compose.yml`** pour servir le build Vite avec **Nginx**.  
L’objectif : à chaque **push sur `main`**, le NAS **tire** le code et **reconstruit** le conteneur.

---

## Vue d’ensemble

| Étape | Rôle |
|--------|------|
| 1–3 | Cloner le dépôt sur le NAS, créer `.env.deploy` |
| 4 | Premier déploiement manuel (`docker compose up`) |
| 5–7 | Conteneur **webhook** qui exécute un script au push Gitea |
| 8 | Configurer le **webhook** dans Gitea (URL + secret en query) |
| 9–10 | **Proxy inverse** Synology + HTTPS pour l’accès extérieur |
| 11–12 | Vérifications et dépannage |

Chemins d’exemple : `/volume1/docker/jira-descours/` — à adapter à ton volume DSM.

---

## 1. Préparer un dossier sur le NAS

En **SSH** (utilisateur admin ou compte avec droits `docker`) :

```sh
mkdir -p /volume1/docker/jira-descours
cd /volume1/docker/jira-descours
```

---

## 2. Cloner le dépôt Gitea (une fois)

Utilise l’URL **SSH** ou **HTTPS** de ton Gitea.

**Dépôt privé (recommandé)** : créer une **clé SSH** sur le NAS, enregistrer la clé **publique** dans Gitea  
(*Paramètres du dépôt → Clés de déploiement* ou compte utilisateur → Clés SSH).

```sh
cd /volume1/docker/jira-descours
git clone git@GITEA_HOST:UTILISATEUR/jira-descours.git src
cd src
```

Le dossier `src` contiendra le `docker-compose.yml` à la racine du dépôt après clone.

---

## 3. Fichier d’environnement de build `.env.deploy`

Sur le NAS, dans **`src/`** (racine du clone) :

```sh
cp .env.deploy.example .env.deploy
nano .env.deploy
```

Renseigne au minimum :

- **`JIRA_DOMAIN`** — sous-domaine Atlassian (comme en dev).
- **`VITE_JIRA_BASE_URL`** — URL **HTTPS** de ton **proxy Jira** (obligatoire en prod : le navigateur n’utilise pas le proxy Vite du `npm run dev`).

Optionnel : `VITE_JIRA_*` comme dans `.env.example`.

**`HOST_PORT`** : port sur lequel le NAS écoute (ex. `8080`). Tu le brancheras ensuite sur le **proxy inverse** DSM.

Ne **commit pas** `.env.deploy` (déjà ignoré par `.gitignore`).

---

## 4. Premier build manuel

Toujours dans `src/` :

```sh
docker compose --env-file .env.deploy up -d --build
```

Teste en local (LAN) : `http://IP_DU_NAS:8080` (ou le port choisi).

---

## 5. Script de déploiement appelé par le webhook

Toujours sur le NAS, crée un script **hors** du dépôt (pour ne pas l’écraser au `git pull`), par ex. :

```sh
sudo tee /volume1/docker/jira-descours/deploy.sh <<'EOF'
#!/bin/sh
set -e
APP_DIR="/volume1/docker/jira-descours/src"
cd "$APP_DIR"
git pull --ff-only
docker compose --env-file .env.deploy -f docker-compose.yml up -d --build
EOF
sudo chmod +x /volume1/docker/jira-descours/deploy.sh
```

Adapte **`APP_DIR`** si ton chemin diffère.

---

## 6. Fichier `hooks.json` pour [adnanh/webhook](https://github.com/adnanh/webhook)

Copie `deploy/hooks.json.example` vers le NAS, par ex. :

`/volume1/docker/jira-descours/hooks.json`

1. Remplace **`CHANGEME_SECRET_TOKEN`** par un **secret long** (génère-en un et garde-le pour Gitea).
2. Vérifie que **`refs/heads/main`** correspond à ta branche de prod (sinon change la valeur).

---

## 7. Lancer le récepteur webhook (Docker)

Le conteneur webhook doit pouvoir exécuter **`docker`** : montage du socket Docker.

**Choisir une IP joignable depuis le conteneur Gitea** :

- Gitea **hors Docker** sur le NAS → souvent `http://127.0.0.1:PORT` depuis le NAS… mais le webhook doit écouter sur une interface que Gitea peut appeler.
- Gitea **dans Docker** sur le même hôte → souvent `http://172.17.0.1:9888` (bridge Docker vers l’hôte) ou **l’IP LAN du NAS** (`http://192.168.x.x:9888`).

Exemple (adapter chemins et tag d’image) :

```sh
docker run -d --name gitea-deploy-hook --restart unless-stopped \
  -p 127.0.0.1:9888:9000 \
  -v /volume1/docker/jira-descours/hooks.json:/etc/webhook/hooks.json:ro \
  -v /volume1/docker/jira-descours/deploy.sh:/config/deploy.sh:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/adnanh/webhook:2.8.2 \
  -verbose -hooks=/etc/webhook/hooks.json
```

- **`-p 127.0.0.1:9888:9000`** : le hook n’est pas exposé sur toute la carte réseau (plus sûr). Gitea sur le **même hôte** doit joindre `127.0.0.1:9888` **depuis l’hôte** ; si Gitea est **dans un autre conteneur**, utilise plutôt l’IP LAN du NAS et `-p 9888:9000` **avec pare-feu** ou réseau Docker partagé.

Vérifie la doc de ton image `webhook` pour le chemin des hooks (`-hooks=...`).

Test manuel (depuis le NAS) :

```sh
curl "http://127.0.0.1:9888/hooks/jira-descours-deploy?token=CHANGEME_SECRET_TOKEN" \
  -X POST -H "Content-Type: application/json" \
  -d '{"ref":"refs/heads/main"}'
```

Le hook doit s’exécuter (voir logs du conteneur `gitea-deploy-hook`).

---

## 8. Webhook dans Gitea

1. Ouvre le dépôt → **Paramètres** → **Webhooks** → **Ajouter un webhook** → **Gitea**.
2. **URL cible** (exemple si hook sur le NAS, port 9888, secret en query) :

   `http://IP_LAN_DU_NAS:9888/hooks/jira-descours-deploy?token=TON_SECRET_LONG`

   Si Gitea et le hook sont sur le **même** OS Docker, teste d’abord avec l’IP LAN ; ajuste selon ce qui fonctionne chez toi.

3. **Déclencher sur** : « Push » (événements de push).
4. Branche : si l’UI le permet, limite à **`main`** ; sinon le filtre est déjà dans `hooks.json` (`ref`).

Enregistre, puis **« Test de livraison »** ou un **push** sur `main` : le site doit se reconstruire après quelques minutes.

---

## 9. Accès depuis l’extérieur (HTTPS)

1. **Nom de domaine** ou **DDNS Synology** pointant vers l’IP publique de ta box.
2. **Box internet** : redirection **TCP 443** (et éventuellement **80**) vers l’**IP du NAS** (même ports ou ceux de ton reverse proxy).
3. Sur DSM : **Panneau de configuration** → **Portail de connexion** → **Proxy inverse** :
   - **Nom d’hôte** : ex. `jira-descours.mondomaine.fr`
   - **Destination** : `http://127.0.0.1:8080` (ou le `HOST_PORT` défini dans `.env.deploy`)
   - **HTTPS** activé, certificat Let’s Encrypt pour ce nom d’hôte.

4. Accès : `https://jira-descours.mondomaine.fr`

**Alternative sans ouvrir les ports** : [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) sur le NAS (très courant en homelab).

---

## 10. Sécurité (rappel court)

- Secret **long** dans l’URL du webhook ; ne le commite pas.
- Préférer le hook en **127.0.0.1** si Gitea appelle depuis la même machine ; sinon **pare-feu** DSM limitant le port du hook aux IP de confiance.
- Mettre à jour DSM, Gitea et les images Docker régulièrement.

---

## 11. Check-list après un push

- Gitea → **Paramètres du dépôt** → **Webhooks** : dernière livraison en vert.
- Sur le NAS : `docker logs gitea-deploy-hook` puis `docker ps` : conteneur `web` à jour.
- Site public : hard refresh (Ctrl+F5) pour éviter le cache du navigateur.

---

## 12. Dépannage

| Problème | Piste |
|----------|--------|
| `git pull` échoue | Clé SSH / droits dépôt ; URL du `origin`. |
| Build Docker OOM | NAS peu de RAM : build sur une machine CI puis `docker pull` (évolution). |
| Page blanche / erreur Jira | `VITE_JIRA_BASE_URL` absent ou incorrect au **build** ; refaire `up --build` après correction de `.env.deploy`. |
| Webhook jamais reçu | URL depuis le conteneur Gitea (test `curl` depuis **dedans** le conteneur Gitea vers l’URL du hook). |
| 403 Let’s Encrypt | Ports 80/443 bien redirigés ; nom DNS correct. |

---

## Fichiers utiles dans ce dépôt

| Fichier | Rôle |
|---------|------|
| `Dockerfile` | Build Node + image Nginx |
| `docker-compose.yml` | Service `web` + args de build |
| `docker/nginx.conf` | SPA `try_files` → `index.html` |
| `.env.deploy.example` | Modèle pour le NAS |
| `deploy/hooks.json.example` | Modèle webhook |
| `deploy/nas-deploy.sh.example` | Ancienne variante (script dans le dépôt) ; le guide privilégie `deploy.sh` **sur le NAS** |

---

## Variante : Gitea Actions + runner sur le NAS

Si tu préfères tout voir dans l’UI Gitea : active **Actions**, installe **act_runner** sur le NAS, enregistre-le sur ton instance, puis ajoute un workflow `.gitea/workflows/deploy.yml` qui exécute les mêmes commandes que `deploy.sh`. C’est plus lourd à configurer (dont l’accès sécurisé à `docker.sock`) mais très propre à long terme.