feat: add Gitea Actions CI/CD, local checks and deploy guide
This commit is contained in:
+278
@@ -0,0 +1,278 @@
|
||||
= 🚀 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]
|
||||
----
|
||||
# Apache + PHP (choix retenu pour ce guide ; Nginx possible, voir §5)
|
||||
apt update && apt upgrade -y
|
||||
apt install -y apache2 php libapache2-mod-php \
|
||||
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
|
||||
----
|
||||
|
||||
== 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 conf/.htaccess.sample .htaccess
|
||||
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
|
||||
# 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 — Apache (recommandée, `.htaccess` fourni)
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
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`.
|
||||
|
||||
=== Option B — Nginx + PHP-FPM
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
apt install -y nginx php-fpm
|
||||
# Adapter conf/nginx.conf.sample : server_name, root, socket php-fpm,
|
||||
# chemins des certificats. ⚠️ Le bloc "location ~* \.(php|inc|...)$ { deny all; }"
|
||||
# de l'exemple correspond à TOUS les .php : le restreindre à ^/includes/.
|
||||
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
|
||||
----
|
||||
|
||||
== 6️⃣ HTTPS (obligatoire pour la PWA)
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
apt install -y certbot python3-certbot-apache # ou python3-certbot-nginx
|
||||
certbot --apache -d example.com -d www.example.com
|
||||
# ou : certbot --nginx -d example.com -d www.example.com
|
||||
----
|
||||
|
||||
== 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 déployer. Elle est *différente* de la deploy key de lecture (étape 3) : celle-ci doit pouvoir écrire dans le clone.
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
# Générer la paire SUR VOTRE POSTE (pas sur le serveur)
|
||||
ssh-keygen -t ed25519 -f annu-kute-ced-deploy -C "ci-gitea-annu-kute-ced"
|
||||
|
||||
# Autoriser la clé publique pour l'utilisateur deploy
|
||||
sudo -u deploy tee -a /home/deploy/.ssh/authorized_keys < annu-kute-ced-deploy.pub
|
||||
----
|
||||
|
||||
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`)
|
||||
|
||||
| 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/`
|
||||
|
||||
| `php-intl` manquant
|
||||
| `apt install php-intl && systemctl restart apache2`
|
||||
|===
|
||||
|
||||
== 🔒 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]
|
||||
Reference in New Issue
Block a user