7.5 KiB
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 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
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 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. 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.
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 :
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. C'est là que le compte de l'étape 3 sert.
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.
5. Raccorder le runner
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 :
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
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
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 :
- Le label
minio-mc:docker://minio/mc:latest— imagemcfournie aux jobs qui le demandent enruns-on. - L'action
lafrite/minio-deploy-action, appelée en URL absolue dans les workflows, qui consomme les secrets ActionsMINIO_ENDPOINT,MINIO_ACCESS_KEYetMINIO_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 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 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 :