fix(forgejo): change runner config

stacks/forge.opytex.org/README.md

@@ -23,7 +23,8 @@ valeur — il faut `--force-recreate`.
 
 ## Mise en service, dans l'ordre
 
-Les quatre étapes ci-dessous sont à faire une seule fois, en séquence.
+Les cinq étapes ci-dessous sont à faire une seule fois, **dans cet ordre**.
+L'ordre n'est pas indifférent : voir l'étape 3.
 
 ### 1. Remplir les secrets
 
@@ -49,11 +50,36 @@ Application + provider OAuth2/OpenID, avec pour URL de redirection :
 https://forge.opytex.org/user/oauth2/authentik/callback
 ```
 
-Le segment `authentik` est le nom donné à la source à l'étape 3 : les deux
+Le segment `authentik` est le nom donné à la source à l'étape 4 : les deux
 doivent coïncider. Le reste de l'URL suit `FORGEJO__server__ROOT_URL` — si le
 domaine de la forge change, cette redirection doit changer avec lui.
 
-### 3. Déclarer la source d'authentification
+### 3. Créer le compte administrateur local
+
+**Avant toute connexion SSO.** Forgejo donne les droits d'administration au
+premier utilisateur créé : si quelqu'un se connecte via Authentik avant cette
+étape, c'est son compte personnel qui devient administrateur de l'instance.
+
+```bash
+sops exec-env secrets.env.yaml 'docker compose exec -u git forgejo \
+  forgejo admin user create --admin \
+    --username waha-local \
+    --email waha-local@opytex.org \
+    --random-password'
+```
+
+Le mot de passe s'affiche une seule fois : le ranger dans `pass` immédiatement.
+
+Ce compte est **volontairement local**, hors SSO. C'est la même porte de secours
+que sur `paperless.opytex.org` : il reste utilisable si Authentik tombe ou si la
+configuration OIDC est cassée — y compris pour réparer cette configuration.
+
+Il est aussi volontairement **distinct de tout compte personnel** : les comptes
+nominatifs créés par SSO restent des utilisateurs ordinaires. Après la première
+connexion SSO, vérifier dans *Administration → Utilisateurs* qu'aucun compte
+nominatif ne porte le drapeau administrateur, et le retirer le cas échéant.
+
+### 4. Déclarer la source d'authentification
 
 Une seule fois, forge démarrée :
 
@@ -75,27 +101,46 @@ Le trio `DISABLE_REGISTRATION` / `ALLOW_ONLY_EXTERNAL_REGISTRATION` /
 `ENABLE_AUTO_REGISTRATION` d'`env_file` est contre-intuitif : mettre
 `DISABLE_REGISTRATION=true`, ce qui semble être le réglage prudent, bloque
 aussi l'auto-création via Authentik et **verrouille la forge pour tout le
-monde**. Un compte admin local créé tôt évite d'y rester enfermé.
+monde**. C'est là que le compte de l'étape 3 sert.
 
-### 4. Enregistrer le runner
+L'auto-création vaut pour **toute personne autorisée par Authentik** à atteindre
+l'application. Restreindre cet accès est un réglage d'Authentik, pas de Forgejo :
+lier un groupe à l'application, sans quoi n'importe quel compte de l'annuaire se
+verra ouvrir un compte sur la forge à sa première visite.
 
-Le runner **ne s'auto-enregistre pas** par variable d'environnement — le runner
-v13 ignore une partie des variables `GITEA_*`, et un jeton passé par
-l'environnement finit tôt ou tard dans l'historique git.
+### 5. Raccorder le runner
 
-Récupérer un jeton dans *Administration → Runners*, puis :
+Il n'y a **pas d'étape d'enregistrement** : la sous-commande `register` du
+runner est dépréciée. C'est la forge qui crée le runner et délivre un couple
+**UUID + jeton**, que le démon présente ensuite comme un identifiant et un mot
+de passe.
+
+Dans *Administration → Actions → Runners*, créer un runner. La page affiche
+l'UUID et le jeton — **le jeton n'est montré qu'une fois.**
+
+**a.** Reporter l'UUID dans `runner/config.yaml`, à la place de
+`REMPLACER-UUID-DU-RUNNER`. Ce n'est pas un secret, il reste en clair dans le
+dépôt.
+
+**b.** Déposer le jeton dans le volume. Il ne doit toucher ni le dépôt, ni le
+disque de l'hôte, ni l'historique du shell — d'où la lecture sur l'entrée
+standard :
 
 ```bash
-docker compose run --rm runner forgejo-runner register \
-  --no-interactive \
-  --instance https://forge.opytex.org \
-  --token <JETON> \
-  --name poney \
-  --config /config.yaml
+sops exec-env secrets.env.yaml 'docker compose run --rm --entrypoint sh runner \
+  -c "umask 077; cat > /data/runner-token"'
+# coller le jeton, puis Ctrl-D
 ```
 
-Le résultat est écrit dans `/data/.runner` (volume `forgejo_runner_data`) et le
-jeton n'est plus jamais nécessaire. Puis `docker compose up -d runner`.
+**c.** Démarrer : `sops exec-env secrets.env.yaml 'docker compose up -d runner'`.
+
+Le runner doit apparaître « en ligne » dans l'administration.
+
+Le jeton vit dans `forgejo_runner_data`, donc `docker compose up -d
+--force-recreate` et les redémarrages le préservent. Seul un `down -v` — qui
+détruirait aussi tous les dépôts — le ferait disparaître. Dans ce cas :
+supprimer le runner dans l'administration, en créer un neuf, et refaire **a**
+et **b** ; l'UUID change à chaque fois.
 
 ## Dépendance MinIO
 
@@ -117,7 +162,7 @@ préavis. Rien n'est changé ici, c'est un constat.
 |---|---|---|
 | `forgeopytexorg_forgejo_data` | **tous les dépôts**, config, avatars, paquets | label `backup.enable=true` |
 | `forgeopytexorg_forgejo_db` | base PostgreSQL | dump SQL (`backup.type=postgres` sur le conteneur) |
-| `forgeopytexorg_forgejo_runner_data` | le seul fichier `.runner` | non sauvegardé — se refait en une commande |
+| `forgeopytexorg_forgejo_runner_data` | le jeton du runner (`runner-token`) | non sauvegardé — se recrée depuis l'administration |
 
 Les labels de volume ne s'appliquent qu'à la création : ceux-ci sont donc
 effectifs. Ne pas en retirer ni en ajouter par la suite — Compose détecte la

stacks/forge.opytex.org/docker-compose.yml

@@ -67,10 +67,11 @@ services:
 
 
   runner:
-    image: code.forgejo.org/forgejo/runner:13.0.0
+    image: data.forgejo.org/forgejo/runner:13
     restart: unless-stopped
     depends_on:
       - forgejo
+    # URL, UUID et emplacement du jeton sont dans runner/config.yaml.
     command: ["forgejo-runner", "daemon", "--config", "/config.yaml"]
     volumes:
       - ./runner/config.yaml:/config.yaml:ro

stacks/forge.opytex.org/runner/config.yaml

@@ -1,19 +1,29 @@
-# Configuration du Forgejo Runner.
-# L'enregistrement n'est PAS fait par variable d'environnement : il se fait une
-# fois, à la main, et le résultat vit dans /data/.runner (volume
-# forgejo_runner_data). Voir README.md.
+# Configuration du Forgejo Runner (v13).
+#
+# Ce fichier est versionné en clair : il ne doit contenir AUCUN secret. Le
+# jeton du runner est lu dans le volume via `token_url` — voir README.md.
+#
+# Les valeurs non mentionnées ici gardent les défauts de l'image. Pour les
+# revoir : `docker compose run --rm --entrypoint forgejo-runner runner
+# generate-config`.
 
 log:
+  # Sortie du processus runner.
   level: info
+  # Ce qui remonte dans le journal du job, visible dans l'interface web.
+  job_level: info
 
 runner:
-  file: /data/.runner
+  # 4 jobs simultanés, comme l'ancien runner. Le défaut de l'image est 1.
   capacity: 4
   timeout: 3h
-  shutdown_timeout: 0s
-  insecure: false
-  fetch_timeout: 5s
   fetch_interval: 2s
+  insecure: false
+
+  # Les labels associent un `runs-on` de workflow à une image.
+  # Ces images viennent du registre de Gitea : elles sont conservées telles
+  # quelles parce que les workflows existants supposent leur outillage.
+  # En changer romprait des builds sans prévenir.
   labels:
     - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
     - "ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04"
@@ -24,24 +34,42 @@ runner:
     - "minio-mc:docker://minio/mc:latest"
 
 cache:
+  # Fournit ACTIONS_CACHE_URL aux workflows qui utilisent l'action `cache`.
   enabled: true
-  dir: ""
+  # Adresse annoncée aux conteneurs de job pour joindre le proxy de cache.
+  # Vide = détection automatique, correcte tant que le démon Docker tourne sur
+  # la même machine que le runner. C'est ici qu'il faut forcer une IP si
+  # `actions/cache` reste bloqué.
   host: ""
-  port: 0
-  external_server: ""
 
 container:
   network: ""
   privileged: false
-  options:
-  workdir_parent:
+  # Aucun volume montable par les jobs.
   valid_volumes: []
-  # Vide = le socket Docker de l'hôte est monté dans les conteneurs de job,
-  # ce qu'exige docker/build-push-action (notytex). Conséquence assumée : tout
-  # job Actions s'exécute en root sur la machine hôte.
-  docker_host: ""
+
+  # ATTENTION AU SENS DE CETTE VALEUR — il a changé en v13.
+  #   "-" ou ""    : aucun socket Docker monté dans le conteneur de job
+  #   "automount"  : socket de l'hôte détecté et monté (défaut d'avant la v13)
+  # `automount` est nécessaire à docker/build-push-action (notytex). En
+  # contrepartie, tout job Actions dispose du démon Docker de l'hôte, donc de
+  # droits équivalents à root sur chioggia.
+  docker_host: "automount"
+
+  # Retire les images à chaque exécution plutôt que de réutiliser une copie
+  # locale. Indispensable ici : le label `minio-mc` pointe sur un tag flottant
+  # (`latest`). Le défaut de l'image est `false`.
   force_pull: true
   force_rebuild: false
 
-host:
-  workdir_parent:
+server:
+  connections:
+    forgejo:
+      url: https://forge.opytex.org/
+      # L'UUID identifie le runner : ce n'est pas un secret, il tient le rôle
+      # d'un nom d'utilisateur.
+      uuid: 0c25170d-cac2-4342-810e-2880e8833b95
+      # Le jeton, lui, en est un. Il vit dans le volume forgejo_runner_data et
+      # n'apparaît donc jamais dans le dépôt. `token` et `token_url` sont
+      # mutuellement exclusifs : ne pas ajouter `token:` ici.
+      token_url: file:///data/runner-token