annu-kute-ced/DEPLOY.adoc

= 🚀 DEPLOY — Mise en production et CI/CD
:toc: left
:toc-title: Sommaire
:toclevels: 3

Ce document décrit la mise en production complète d'*ANNU KUTE CED* sur un serveur fraîchement installé, puis l'activation du déploiement continu via *Gitea Actions*.

Il est complémentaire au link:README.adoc[README] (installation manuelle, configuration de l'application).

== 🧭 Vue d'ensemble

L'architecture retenue (identique à celle de pawol.nu) :

[source]
----
┌─────────────┐   push main    ┌──────────────────┐   SSH (git pull)   ┌─────────────┐
│  Dépôt git  │ ─────────────▶│  Gitea Actions   │ ─────────────────▶│  Serveur    │
│  (LaBola)   │                │  check → deploy  │                    │  production │
└─────────────┘                └──────────────────┘                    └─────────────┘
----

. *Vérification* (`check-pr.yml` + job `check` de `deploy-prod.yml`) : lint PHP/JS, validation AsciiDoc, JSON, XML, shellcheck. Les mêmes vérifications sont exécutables en local avec `scripts/check.sh`.
. *Déploiement* (`deploy-prod.yml`) : le runner se connecte en SSH au serveur, qui tient *un clone du dépôt*, fait `git pull --ff-only`, puis *bumpe la version des caches* du Service Worker (`sw.js`) pour déclencher le modal de mise à jour PWA chez les visiteurs.

Pourquoi un `git pull` sur le serveur plutôt qu'un rsync : tous les fichiers propres à l'instance (`config.local.php`, `.htaccess`, `sitemap.xml`, `robots.txt`, `site.webmanifest`, `mentions-legales.php`, `dons.php`, `uploads/`, `cache/`) sont ignorés par Git — un pull ne les écrase jamais. Le déploiement est ainsi sans risque pour la configuration de production.

== 📋 Prérequis

- Un serveur *Debian 12* ou *Ubuntu 24.04* fraîchement installé, avec accès `root` (ou `sudo`)
- Un nom de domaine dont le *DNS pointe vers le serveur* (enregistrement A/AAAA)
- Le dépôt Gitea : `git@labola.o-k-i.net:cedric/annu-kute-ced.git`
- Un *runner Gitea Actions* opérationnel sur l'instance LaBola (déjà le cas pour pawol.nu)

NOTE: Sur un hébergement mutualisé (pas d'accès root), adaptez : les fichiers sont déployés dans le docroot fourni par l'hébergeur, et la clé SSH s'ajoute via le panneau de contrôle (o2switch : *Clés SSH* dans cPanel).

== 1️⃣ Installation des paquets

[source,bash]
----
# Nginx + PHP-FPM (choix recommandé ; Apache possible, voir §5 option B)
apt update && apt upgrade -y
apt install -y nginx php-fpm \
    php-curl php-intl php-mbstring php-xml \
    git curl unzip

# Vérifier les extensions requises
php -m | grep -E 'curl|intl|mbstring|SimpleXML|json'
----

== 2️⃣ Utilisateur de déploiement

Le runner CI se connectera en SSH avec cet utilisateur. Ne *pas* utiliser root.

[source,bash]
----
adduser --disabled-password --gecos "Deploy annu-kute-ced" deploy
usermod -aG www-data deploy

# Répertoire de l'application
mkdir -p /var/www/annu-kute-ced
chown -R deploy:www-data /var/www/annu-kute-ced

# Répertoire SSH de l'utilisateur deploy (préparé pour les clés publiques)
mkdir -p /home/deploy/.ssh
chmod 700 /home/deploy/.ssh
chown -R deploy:deploy /home/deploy/.ssh
----

== 3️⃣ Clone du dépôt

Le serveur de production tient un clone du dépôt. Le runner y exécutera `git pull` à chaque déploiement.

[source,bash]
----
# Clé SSH du serveur pour lire le dépôt (deploy key Gitea, lecture seule)
sudo -u deploy ssh-keygen -t ed25519 -f /home/deploy/.ssh/id_ed25519 -N ""
cat /home/deploy/.ssh/id_ed25519.pub
----

. Sur LaBola : *Settings du dépôt → Deploy Keys → Add deploy key* (coller la clé publique, lecture seule suffit).
. Puis :
+
[source,bash]
----
sudo -u deploy git clone git@labola.o-k-i.net:cedric/annu-kute-ced.git /var/www/annu-kute-ced
cd /var/www/annu-kute-ced
sudo -u deploy git config pull.ff only   # sécurité : refuser tout pull non fast-forward
----

== 4️⃣ Fichiers d'instance

Ces fichiers sont ignorés par Git : ils vivent *uniquement sur le serveur* et ne seront jamais écrasés par les déploiements.

[source,bash]
----
cd /var/www/annu-kute-ced
sudo -u deploy cp includes/config.local.php.sample includes/config.local.php
sudo -u deploy cp site.webmanifest.sample site.webmanifest
sudo -u deploy cp robots.txt.sample robots.txt
sudo -u deploy cp sitemap.xml.sample sitemap.xml
sudo -u deploy cp mentions-legales.php.sample mentions-legales.php
# Uniquement si vous utilisez Apache (option B de l'étape 5) :
# sudo -u deploy cp conf/.htaccess.sample .htaccess
# Facultatif (page de dons) :
# sudo -u deploy cp dons.php.sample dons.php
----

Éditer ensuite les fichiers copiés :

- `includes/config.local.php` : `APP_HOST_NAME`, sources (PeerTube/Castopod/Mastodon), `CACHE_ENABLED=true` (recommandé pour Castopod), etc. — voir la link:README.adoc#fr-configuration[référence de configuration]
- `sitemap.xml`, `robots.txt`, `site.webmanifest` : remplacer `example.com` par le domaine réel
- `mentions-legales.php` : remplacer le placeholder `VOTRE-DATE-MAJ`

[source,bash]
----
# Le cache de l'API doit être accessible en écriture par PHP
mkdir -p /var/www/annu-kute-ced/cache
chown -R www-data:www-data /var/www/annu-kute-ced/cache
----

== 5️⃣ VirtualHost

=== Option A — Nginx + PHP-FPM (recommandée, configuration fournie)

Le fichier `conf/nginx.conf.sample` est l'équivalent Nginx complet du `.htaccess` : mêmes protections (fichiers de configuration, répertoires sensibles, dotfiles, pas de listing), masquage de l'extension `.php`, `no-cache` pour `sw.js` et `site.webmanifest`, plus le cache des assets et gzip.

Il est conçu pour un déploiement *en deux temps* : le bloc `:80` sert immédiatement le site en HTTP (prérequis de la validation Certbot, étape 6), et `certbot --nginx` créera ensuite le bloc `443` avec la redirection HTTPS. Aucun certificat n'est donc requis à cette étape — `nginx -t` doit passer tel quel.

[source,bash]
----
# Adapter conf/nginx.conf.sample :
#   - server_name  : votre domaine
#   - root         : /var/www/annu-kute-ced
#   - fastcgi_pass : socket de votre version PHP (ex. /var/run/php/php8.3-fpm.sock)
cp conf/nginx.conf.sample /etc/nginx/sites-available/annu-kute-ced
ln -s /etc/nginx/sites-available/annu-kute-ced /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
----

=== Option B — Apache

[source,bash]
----
apt install -y apache2 php libapache2-mod-php
a2enmod rewrite headers
cat > /etc/apache2/sites-available/annu-kute-ced.conf <<'EOF'
<VirtualHost *:80>
    ServerName example.com
    ServerAlias www.example.com
    DocumentRoot /var/www/annu-kute-ced

    <Directory /var/www/annu-kute-ced>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
EOF
a2ensite annu-kute-ced
systemctl reload apache2
----

Le `.htaccess` copié à l'étape 4 applique les règles de sécurité, le HTTPS forcé (actif après l'étape 6) et le `no-cache` de `sw.js`.

== 6️⃣ HTTPS (obligatoire pour la PWA)

Méthode recommandée par l'EFF : *Certbot via snap* (https://certbot.eff.org/instructions?ws=nginx&os=snap[instructions officielles^]). Prérequis : le domaine pointe vers le serveur et le site répond déjà en HTTP sur le port 80 (étape 5 terminée).

[source,bash]
----
# 1. Installer snapd (Ubuntu : déjà présent. Debian : apt + support classic)
apt install -y snapd
snap install core && snap refresh core

# 2. Retirer tout certbot installé via apt (évite les conflits de commande)
apt-get remove -y certbot || true

# 3. Installer Certbot et préparer la commande
snap install --classic certbot
ln -s /snap/bin/certbot /usr/local/bin/certbot

# 4. Obtenir le certificat ET laisser Certbot configurer Nginx automatiquement
certbot --nginx -d example.com -d www.example.com
# Variante prudente (ne fait qu'émettre le certificat, vhost édité à la main) :
# certbot certonly --nginx -d example.com -d www.example.com

# 5. Vérifier le renouvellement automatique (timer systemd/cron inclus avec le snap)
certbot renew --dry-run
----

NOTE: Pour Apache (option B), la méthode snap est identique, avec `certbot --apache` à l'étape 4.

Ouvrez ensuite `https://example.com` dans un navigateur : le cadenas doit apparaître dans la barre d'URL.

== 7️⃣ Vérification du site

[source,bash]
----
curl -I https://example.com
# Attendu : HTTP/2 200, en-têtes de sécurité (CSP, X-Frame-Options…)
curl -I https://example.com/sw.js
# Attendu : Cache-Control: no-cache
----

Ouvrir le site dans un navigateur : vidéos, podcasts, timeline et le bouton d'installation PWA doivent fonctionner.

== 8️⃣ Clé SSH du CI

C'est la clé utilisée par le runner Gitea Actions pour se connecter au serveur et déployer. Elle est *différente* de la deploy key de lecture (étape 3) : celle-ci doit pouvoir écrire dans le clone.

Générez la paire de clés *sur votre poste local* (pas sur le serveur), puis transférez la clé publique sur le serveur pour l'autoriser.

[source,bash]
----
# Sur votre poste local
ssh-keygen -t ed25519 -f annu-kute-ced-deploy -C "ci-gitea-annu-kute-ced"

# Affichez la clé publique (elle doit être copiée sur le serveur)
cat annu-kute-ced-deploy.pub
----

=== Transfert de la clé publique sur le serveur

Option A — copie directe avec `scp` (depuis votre poste) :

[source,bash]
----
# Sur votre poste local (adapter user@serveur si vous ne vous connectez pas en root)
scp annu-kute-ced-deploy.pub root@<IP_DU_SERVEUR>:/tmp/annu-kute-ced-deploy.pub

# Puis sur le serveur, ajoutez-la au fichier authorized_keys de deploy
sudo -u deploy mkdir -p /home/deploy/.ssh
sudo -u deploy tee -a /home/deploy/.ssh/authorized_keys < /tmp/annu-kute-ced-deploy.pub
----

Option B — connexion SSH sur le serveur, puis création manuelle du fichier :

[source,bash]
----
# Sur le serveur, connecté en root ou avec sudo
sudo -u deploy mkdir -p /home/deploy/.ssh
sudo -u deploy tee -a /home/deploy/.ssh/authorized_keys
# Coller le contenu de annu-kute-ced-deploy.pub, puis Ctrl+D
----

Quelle que soit la méthode, vérifiez les permissions :

[source,bash]
----
chown -R deploy:deploy /home/deploy/.ssh
chmod 700 /home/deploy/.ssh
chmod 600 /home/deploy/.ssh/authorized_keys
----

=== Test de la connexion CI

Avant d'enregistrer la clé privée dans Gitea, testez depuis votre poste que la connexion fonctionne avec la clé privée générée :

[source,bash]
----
# Sur votre poste local
ssh -i annu-kute-ced-deploy deploy@<IP_DU_SERVEUR> "whoami && hostname"
# Attendu : "deploy" et le nom du serveur, sans mot de passe demandé
----

La clé privée (`annu-kute-ced-deploy`, sans passphrase) ira dans les secrets Gitea à l'étape suivante. *Conservez-la en lieu sûr et ne la commitez jamais.*

== 9️⃣ Secrets Gitea

Dans LaBola : *Settings du dépôt → Actions → Secrets*, créer :

[cols="1,3",options="header"]
|===
| Secret | Valeur

| `SSH_HOST`
| Adresse du serveur (IP ou FQDN), port 22 par défaut (sinon `host:port`)

| `SSH_USER`
| `deploy`

| `SSH_KEY`
| Contenu *intégral* de la clé privée générée à l'étape 8

| `PROD_DEPLOY_PATH`
| `/var/www/annu-kute-ced`
|===

WARNING: `SSH_KEY` donne un accès shell au serveur avec les droits de `deploy`. Ne jamais la coller ailleurs que dans les secrets Gitea, et révoquer la clé publique (`authorized_keys`) en cas de doute.

== 🔟 Test du pipeline

. Pousser un commit sur `main` (par exemple une correction de coquille dans le README).
. Dans LaBola, onglet *Actions* : le workflow *Déploiement PROD* doit exécuter `check` puis `deploy` au vert.
. Côté serveur :
+
[source,bash]
----
cd /var/www/annu-kute-ced
git log -1 --oneline        # doit correspondre au commit poussé
grep STATIC_CACHE_NAME sw.js # le suffixe de version a été bumpé à l'heure du déploiement
----
. Côté visiteur : au prochain chargement de page, le modal « Nouvelle version disponible » apparaît (Service Worker déjà installé lors d'une visite précédente).

== 🔄 Fonctionnement courant

[cols="1,3",options="header"]
|===
| Événement | Résultat

| Pull request vers `main`
| Workflow *Vérification PR* : lints et validations bloquants en cas d'erreur

| Push sur `main`
| Workflow *Déploiement PROD* : mêmes vérifications, puis SSH → `git pull --ff-only` → bump de la version des caches `sw.js` → modal de mise à jour chez les visiteurs

| En local, avant de pousser
| `scripts/check.sh` exécute les mêmes vérifications que le CI
|===

Le bump de version dans `sw.js` est fait *sur le serveur uniquement* : le dépôt garde sa valeur de référence, le working tree du serveur est nettoyé (`git checkout -- sw.js`) avant chaque pull pour garantir le fast-forward.

== 🧰 Dépannage

[cols="1,3",options="header"]
|===
| Symptôme | Piste

| `git pull --ff-only` échoue sur le serveur
| Une modification locale existe : `git status` dans le docroot, puis `git checkout -- <fichier>` (le workflow le fait déjà pour `sw.js`)

| `Permission denied` sur `.git/FETCH_HEAD` (ou un autre fichier `.git`)
| Des fichiers du clone appartiennent à `root` (une commande `git` a été lancée en root, sans `sudo -u deploy`) : `chown -R deploy:www-data /var/www/annu-kute-ced`

| L'action ne se déclenche pas
| Vérifier que le runner act est en ligne (LaBola → *Site Administration → Actions → Runners*) et que Actions est activé pour le dépôt (*Settings → Units*)

| `Permission denied (publickey)` dans le job deploy
| Clé publique absente de `/home/deploy/.ssh/authorized_keys`, ou mauvais `SSH_USER`/`SSH_HOST`

| Les visiteurs ne reçoivent pas la mise à jour
| Vérifier `curl -I https://example.com/sw.js` → `Cache-Control: no-cache` requis (règles fournies dans `conf/`)

| Erreurs 500 sur les vidéos/podcasts
| `cache/` non accessible en écriture : `chown -R www-data:www-data cache/`

| `502 Bad Gateway` (Nginx)
| PHP-FPM injoignable : vérifier le socket réel avec `ls /var/run/php/` et adapter `fastcgi_pass` dans le vhost (ex. `php8.1-fpm.sock` sous Ubuntu 22.04, `php8.3-fpm.sock` sous 24.04) ; vérifier que le service tourne : `systemctl status php*-fpm`

| `php-intl` manquant
| `apt install php-intl` puis `systemctl restart php*-fpm` (Nginx) ou `systemctl restart apache2` (Apache)
|===

== 🔒 Notes de sécurité

- La clé privée du CI est *dédiée* à ce dépôt : une clé compromise ne donne accès qu'au compte `deploy`, sans sudo.
- La deploy key Gitea (étape 3) est en *lecture seule*.
- Pour restreindre davantage la clé du CI, on peut limiter les commandes dans `authorized_keys` (`command="..."`, `no-pty`) — facultatif, hors scope de ce guide.
- Les fichiers sensibles (`includes/`, `.htaccess`, `config.local.php`) sont bloqués en accès web par les configurations fournies dans `conf/`.

== 📞 Support

En cas de blocage : mailto:kontak@o-k-i.net[kontak@o-k-i.net]