Set-OPS-Public/docs/exploitation/theme-forgejo-hors-flotte.md

Appliquer le thème Alliance Boréale à une forge Forgejo hors flotte

Pour qui : l'exploitant d'une forge Forgejo hors de la flotte Set-OPS.

Procédure manuelle, pour une instance Forgejo qui n'est pas gérée par Set-OPS — typiquement la forge historique qui héberge ce dépôt et son wiki.

Pour une forge de la flotte (forge-01), ne rien faire à la main : passer serveur_forgejo_branding: true et déployer le groupe serveur_forgejo. Le rôle copie exactement les mêmes fichiers.

Ce que ça couvre

Forgejo n'offre aucun réglage web pour le CSS personnalisé : il faut déposer un fichier sur le serveur. Une fois en place, la feuille est injectée sur toutes les pages — dépôts, tickets, code, README et wiki. Le wiki n'a pas de thème distinct, il hérite du même habillage.

Prérequis

• accès root (ou sudo) sur la machine qui exécute Forgejo ;
• connaître le répertoire custom de l'instance ;
• une fenêtre où redémarrer le service est acceptable (quelques secondes d'indisponibilité).

Trouver le répertoire custom :

# 1. déclaré explicitement ?
grep -iE '^\s*(CUSTOM_PATH|ROOT)\s*=' /etc/forgejo/app.ini

# 2. ou par la variable d'environnement du service
systemctl show forgejo -p Environment | tr ' ' '\n' | grep -i custom

# 3. défaut usuel des paquets / installs binaires
ls -d /var/lib/forgejo/custom 2>/dev/null

Les fichiers

Les deux fichiers vivent déjà dans ce dépôt — ne pas en faire de copie :

Fichier du dépôt	Destination sur la forge
roles/serveur_forgejo/files/custom/public/assets/css/alliance.css	<custom>/public/assets/css/alliance.css
roles/serveur_forgejo/files/custom/templates/custom/header.tmpl	<custom>/templates/custom/header.tmpl

Optionnels, si l'on veut aussi le logo et la favicon étoile : files/custom/public/assets/img/{logo,favicon}.svg → <custom>/public/assets/img/.

Pose

Depuis une copie locale du dépôt, en remplaçant FORGE et CUSTOM :

FORGE=root@forge.exemple.ca          # hôte de la forge
CUSTOM=/var/lib/forgejo/custom       # répertoire custom trouvé plus haut
SRC=roles/serveur_forgejo/files/custom

scp "$SRC/public/assets/css/alliance.css" "$FORGE:/tmp/alliance.css"

Puis sur la forge :

CUSTOM=/var/lib/forgejo/custom
OWNER=git:git                        # utilisateur du service (souvent git ou forgejo)

install -D -o $OWNER -m 0644 /tmp/alliance.css "$CUSTOM/public/assets/css/alliance.css"

Injecter la feuille — l'étape à ne pas rater

header.tmpl est injecté dans le <head> de toutes les pages.

⚠️ Si le fichier existe déjà, ne pas l'écraser : une autre personnalisation y vit peut-être. Y ajouter la ligne.

CUSTOM=/var/lib/forgejo/custom
LINK='<link rel="stylesheet" href="{{AppSubUrl}}/assets/css/alliance.css?v=1">'
TPL="$CUSTOM/templates/custom/header.tmpl"

if [ -f "$TPL" ]; then
  grep -qF 'alliance.css' "$TPL" || printf '%s\n' "$LINK" >> "$TPL"
else
  install -D -o git:git -m 0644 /dev/null "$TPL"
  printf '%s\n' "$LINK" > "$TPL"
fi

systemctl restart forgejo

Vérifier

# la feuille est servie (200, type CSS)
curl -sI https://forge.exemple.ca/assets/css/alliance.css | head -3

# elle est bien référencée dans le <head> d'une page de wiki
curl -s https://forge.exemple.ca/<proprio>/<depot>/wiki | grep -o 'alliance\.css[^"]*'

À l'œil, sur une page de wiki en thème sombre : fond bleu nuit avec une nappe magenta à droite et verte en bas à gauche, filet d'aurore sous les titres, code en ligne en teal.

Le ciel nocturne ne s'applique qu'aux thèmes sombres (forgejo-dark, forgejo-auto). En thème clair, seules les couleurs d'accent changent — c'est voulu.

Revenir en arrière

CUSTOM=/var/lib/forgejo/custom
sed -i '/alliance\.css/d' "$CUSTOM/templates/custom/header.tmpl"
rm -f "$CUSTOM/public/assets/css/alliance.css"
systemctl restart forgejo

Après une mise à jour de Forgejo

alliance.css est en deux sections (cf. roles/serveur_forgejo/README.md) :

• §1 Variables — surcharge de variables de couleur officielles. Ne casse pas.
• §2 Décor — s'appuie sur des classes internes (.markup h1, .markup blockquote…). À revérifier après chaque montée de version majeure. Si quelque chose déraille, supprimer §2 ramène au thème sobre sans rien perdre d'essentiel.