ORGANISATION-KA-INTERNATIONALE/FEDIVERSE-OKI

Fork 1

Files

T

cedric 84013376f2

docs: prioritize nginx, fix sample config and use certbot snap

2026-07-25 16:44:24 +04:00

12 KiB

Raw Blame History

🚀 DEPLOY — Mise en production et CI/CD

Sommaire

🧭 Vue d’ensemble
📋 Prérequis
1️⃣ Installation des paquets
2️⃣ Utilisateur de déploiement
3️⃣ Clone du dépôt
4️⃣ Fichiers d’instance
5️⃣ VirtualHost
- Option A — Nginx + PHP-FPM (recommandée, configuration fournie)
- Option B — Apache
6️⃣ HTTPS (obligatoire pour la PWA)
7️⃣ Vérification du site
8️⃣ Clé SSH du CI
9️⃣ Secrets Gitea
🔟 Test du pipeline
🔄 Fonctionnement courant
🧰 Dépannage
🔒 Notes de sécurité
📞 Support

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 README (installation manuelle, configuration de l’application).

🧭 Vue d’ensemble

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

┌─────────────┐   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

# 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.

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.

# 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 :

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.

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 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

# 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, HTTPS forcé, no-cache pour sw.js et site.webmanifest, plus le cache des assets et gzip.

# 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)
#   - ssl_certificate(_key) : chemins de vos certificats (étape 6)
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

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 (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).

# 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

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.

# 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 :

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 :

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

É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

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` 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 : kontak@o-k-i.net

12 KiB Raw Blame History Unescape Escape