infra/stacks/forge.opytex.org/README.md

Forgejo — forge.opytex.org

Forge git. Quatre conteneurs : forgejo (l'application), postgres, cache (Valkey) et runner (Forgejo Actions).

Le nom de ce dossier donne le nom de projet Compose forgeopytexorg, dont dérivent forgeopytexorg_forgejo_data et le nom du dump de base. Le renommer ferait repartir la forge sur des volumes vides.

Déploiement

Depuis ce dossier, sur chioggia :

sops exec-env secrets.env.yaml 'docker compose up -d'

Les secrets sont déclarés ${VAR:?} : toute commande docker compose échoue sans l'enveloppe sops exec-env, y compris logs, ps et exec.

Après une rotation de secret, up -d répond « up to date » et garde l'ancienne valeur — il faut --force-recreate.

Mise en service, dans l'ordre

Les quatre étapes ci-dessous sont à faire une seule fois, en séquence.

1. Remplir les secrets

Deux valeurs, toutes deux en placeholder visible (REMPLACER-…) :

sops edit secrets.env.yaml

Clé	Origine
POSTGRES_PASSWORD	à générer (pwgen -s 32 1)
SSO_CLIENT_SECRET	copié depuis le provider Authentik créé à l'étape 2

SSO_CLIENT_SECRET n'est pas lu par le conteneur : il est conservé ici pour ne pas être perdu, et injecté à la main dans la commande add-oauth ci-dessous.

2. Créer le provider OIDC dans Authentik

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

Une seule fois, forge démarrée :

sops exec-env secrets.env.yaml 'docker compose exec -u git forgejo \
  forgejo admin auth add-oauth \
    --name authentik \
    --provider openidConnect \
    --key <CLIENT_ID_AUTHENTIK> \
    --secret "$SSO_CLIENT_SECRET" \
    --auto-discover-url https://sso.opytex.org/application/o/forgejo/.well-known/openid-configuration \
    --scopes "openid email profile"'

Le client_id n'est pas un secret : il peut rester en clair dans cette commande.

Vérifier immédiatement qu'un compte se crée bien à la première connexion. 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é.

4. Enregistrer le runner

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.

Récupérer un jeton dans Administration → Runners, puis :

docker compose run --rm runner forgejo-runner register \
  --no-interactive \
  --instance https://forge.opytex.org \
  --token <JETON> \
  --name poney \
  --config /config.yaml

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.

Dépendance MinIO

runner/config.yaml déclare le label minio-mc. Deux choses en dépendent, à reprendre le jour du passage de storage.opytex.org (MinIO) à Garage :

1. Le label minio-mc:docker://minio/mc:latest — image mc fournie aux jobs qui le demandent en runs-on.
2. L'action lafrite/minio-deploy-action, appelée en URL absolue dans les workflows, qui consomme les secrets Actions MINIO_ENDPOINT, MINIO_ACCESS_KEY et MINIO_SECRET_KEY.

Le tag latest combiné à force_pull: true fait suivre mc en amont sans préavis. Rien n'est changé ici, c'est un constat.

Volumes et sauvegarde

Volume	Contenu	Sauvegarde
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

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 divergence entre le volume et sa déclaration, et propose de le recréer.

forgejo_db n'a délibérément aucun label : sauvegarder les fichiers d'un PostgreSQL en cours d'écriture ne donne pas une base restaurable.

Ajouter forgeopytexorg_forgejo_data à MANUAL_VOLUMES (backup.conf) reste utile en ceinture-bretelles, comme pour les autres stacks — restic déduplique.

Version

Forgejo v15.0.3 (LTS), supportée jusqu'en juillet 2027. La branche non-LTS (v16) a un horizon de support de quelques mois seulement : inadapté pour la forge qui héberge le dépôt infra.

Ne pas monter de version majeure sans sauvegarde vérifiée — les migrations de schéma ne se reviennent pas.

Références :

• https://forgejo.org/docs/latest/admin/
• https://forgejo.org/releases/