GitOps — Forgejo + Renovate + CD¶

Date : 2026-05-07
Statut : ✅ Terminé — stabilisé après correctifs post-déploiement

Objectif¶

Mettre en place un système de mise à jour automatisé à l'échelle du serveur basé sur Git comme source de vérité :

• Renovate détecte les nouvelles versions d'images Docker (toutes les 6h)
• Forgejo héberge les compose files versionnés + crée des PRs automatiquement
• Forgejo Actions déploie via SSH sur Proxmox à chaque merge sur main
• Zot registry sert de proxy pull-through (Docker Hub, GHCR, lscr.io) pour tous les LXC, et résout l'absence d'internet sur LXC 103

Décisions arrêtées¶

Architecture déployée¶

Renovate (cron 06h00)
  → scanne homelab/infra sur git.ncls.ltd
  → PR avec bump version (+ changelog GitHub)

Review (manuelle pour majors, 3j stabilité pour minor/patch)
  → merge → push main

Forgejo Actions (deploy.yml)
  → SSH root@192.168.1.21 (Proxmox host)
  → git pull /mnt/lxc-data
  → pct exec NNN -- docker compose pull && up -d
    (pour LXC 103 : images via Zot 192.168.1.107:5000)

Zot registry (192.168.1.107:5000)
  → pull-through Docker Hub, GHCR, lscr.io onDemand
  → registry-mirrors sur daemon.json de chaque LXC

Structure monorepo /mnt/lxc-data (= homelab/infra)¶

/mnt/lxc-data/
├── .gitignore
├── .forgejo/workflows/
│   ├── renovate.yml         # cron 06h00 + workflow_dispatch
│   └── deploy.yml           # trigger push main → SSH deploy
├── renovate.json5           # majors=review, minor/patch=automerge 3j
├── 100-media/
│   ├── docker-compose.yml   # images épinglées
│   ├── stack.env            # GITIGNORED — PROWLARR_API_KEY
│   └── stack.env.example    # template versionné
├── 101-admin/
│   └── docker-compose.yaml
├── 103-network/
│   ├── docker-compose.yml   # Cup via Zot mirror pour GHCR
│   └── stack.env.example
├── 104-services/
│   └── docker-compose.yml
├── 105-web/
│   └── docker-compose.yml
├── 106-storage/
│   ├── docker-compose.yml
│   ├── stack.env            # GITIGNORED — SFTPGO_OIDC secrets
│   └── stack.env.example
└── 107-forge/
    ├── docker-compose.yml   # Forgejo + Runner + Zot
    └── zot/config.json

Phases d'implémentation¶

Phase 0 — Inventaire versions images¶

Relevé docker inspect sur chaque LXC pour remplacer :latest par tags sémantiques.

Phase 1 — LXC 107 "forge" : Forgejo + Zot¶

• Création LXC 107 (Debian 12, 2GB RAM, 30GB, 192.168.1.107)
• 107-forge/docker-compose.yml : Forgejo (3000), Runner, Zot (5000)
• 107-forge/zot/config.json : pull-through docker.io/ghcr.io/lscr.io
• Caddy : git.ncls.ltd → 192.168.1.107:3000 (pas de SSO — Forgejo gère sa propre auth)
• Authelia : git.ncls.ltd en bypass (Git HTTP + API ne fonctionnent pas derrière SSO)
• daemon.json registry-mirrors sur LXC 100/101/103/104/105/106

Phase 2 — Monorepo + images épinglées¶

• git init /mnt/lxc-data, push vers Forgejo
• Migration secrets → stack.env (gitignored)
• Bump toutes les images :latest → versions sémantiques (Phase 0)
• renovate.json5, stack.env.example par LXC
• .forgejo/workflows/ : renovate.yml + deploy.yml

Phase 3 — Runner + déploiement Forgejo/Zot¶

• Déploiement LXC 107 via pct exec 107 -- docker compose up -d
• Enregistrement Forgejo Actions runner (token UI)
• SSH deploy key ED25519 → authorized_keys Proxmox host
• Secrets Forgejo : PROXMOX_HOST, PROXMOX_SSH_KEY, FORGEJO_RENOVATE_TOKEN, GITHUB_COM_TOKEN

Phase 4 — Validation end-to-end¶

• Test push → deploy workflow → container redémarré sur la bonne version
• Test Renovate dispatch → PR avec changelog
• Test auto-merge 3j (avec date forcée ou bypass)

Phase 5 — LXC 103 : Cup via Zot¶

• Image Cup dans 103-network/docker-compose.yml → 192.168.1.107:5000/mirror/ghcr/sergi0g/cup:<version>
• PackageRule Renovate pour suivi upstream ghcr.io

Phase 6 — Backup + Documentation¶

• backup-docker-configs.sh : ajout 107-forge/ + */stack.env
• Docs : applications/forgejo.md, applications/zot.md, infrastructure/.../107-forge.md
• Mise à jour index.md, proxy.md, sso.md, updates/docker.md

Inventaire images (Phase 0)¶

Note : torznab-proxy (LXC 100) = image build locale, Renovate gère le FROM du Dockerfile.

Conclusion¶

Date de fin : 2026-05-07
Implémentation complète — toutes les étapes exécutées sans intervention manuelle via l'agent Copilot sur root@pve.

Récapitulatif de l'implémentation complète¶

Correctifs appliqués pendant l'implémentation¶

État final (2026-05-07)¶

LXC 107 — 192.168.1.107
├── forgejo:15  (port 3000 HTTP / 2222 SSH)  → healthy ✅
├── forgejo-runner:6  (label: ubuntu-latest)  → idle ✅
└── zot-linux-amd64  (port 5000)             → up ✅

git.ncls.ltd → Caddy (LXC 103) → Forgejo  → 308 redirect confirmé ✅
Registry mirrors → Zot → configurés LXC 100/101/103/104/105/106  ✅
Authelia bypass git.ncls.ltd  → healthy ✅
Monorepo /mnt/lxc-data → homelab/infra sur Forgejo  → 3 commits ✅

Prochaines étapes recommandées¶

1. Ajouter GITHUB_COM_TOKEN dans les secrets Forgejo : optionnel, évite le rate-limiting Docker Hub metadata lors des scans Renovate
2. Déclencher Renovate manuellement : workflow → "Run workflow" pour valider les PRs de mise à jour
3. Tester le workflow deploy : pousser une modif sur un compose → vérifier le déclenchement CD
4. Configurer stabilityDays dans renovate.json5 si les PRs arrivent trop vite (déjà à 3 jours dans le config)

Correctifs post-déploiement — 2026-05-12¶

Tags images — préfixe v manquant¶

Les tags relevés en Phase 0 ne reflétaient pas le format réel des registries ghcr.io et lscr.io :

Renovate — auth manquante¶

Le runner Renovate échouait avec 401. Le PAT renovate-bot avait été créé sans le scope read:user, requis par Renovate pour s'identifier. Recréé avec les scopes complets (write:repository, write:issue, read:organization, read:misc, read:user). Secret RENOVATE_TOKEN mis à jour.

Zot mirror — inaccessible depuis le runner¶

L'image 192.168.1.107:5000/ghcr/sergi0g/cup:v3.5.1 (LXC 103) est inaccessible depuis le runner car il tourne dans LXC 107. Règle ajoutée dans renovate.json5 pour désactiver Renovate sur toute référence 192.168.1.107:5000/*.

Migration — per-app subdirectories¶

Les stacks Portainer ont été migrées vers le monorepo GitOps avec une structure par sous-répertoire :

Le deploy.yml iterate désormais les sous-répertoires après le compose racine de chaque LXC, via un script deploy.sh copié dans le LXC.

Bug deploy — quoting bash -c¶

La boucle for appdir in */ dans le inline bash -c de deploy.yml était inopérante : la variable $appdir était expandée à vide par le shell SSH avant d'atteindre le bash -c. Les sous-stacks n'étaient jamais déployés par CI.

Correctif : deploy.sh (script Shell autonome en racine du monorepo) est copié dans le LXC via pct push puis exécuté directement — sans imbrication de shell, sans ambiguïté de quoting.

Correctifs post-déploiement (session 2 — 2026-05-07)¶

Problèmes rencontrés et solutions¶

1. LXC 107 — daemon.json manquant → pull renovate/renovate timeout¶

Le workflow renovate.yml échouait silencieusement : l'image renovate/renovate était tirée directement depuis docker.io, sans passer par Zot, car LXC 107 n'avait pas de daemon.json configuré.

Solution : Création de /etc/docker/daemon.json sur LXC 107 :

{
  "registry-mirrors": ["http://127.0.0.1:5000"],
  "insecure-registries": ["127.0.0.1:5000", "192.168.1.107:5000"]
}

Complément : Image Renovate épinglée à renovate/renovate:43.169.1 dans renovate.yml (était :latest) — Zot télécharge l'image complète au premier appel (onDemand), les suivants sont servis immédiatement depuis le cache.

2. appleboy/ssh-action non résolu depuis le runner → suppression de tous les uses:¶

Les actions Forgejo hébergées sur data.forgejo.org ne sont pas résolvables depuis les containers de jobs (DNS interne Docker 127.0.0.11 ne résout pas les domaines externes). Tout uses: appleboy/ssh-action@... ou uses: actions/checkout@v4 échouait.

Solution : Suppression de tous les uses: dans deploy.yml. Remplacement par une étape run: native utilisant ssh standard et bash << EOF directement sur l'hôte Proxmox — pas d'action externe nécessaire.

3. Utilisateur dédié renovate-bot¶

Contexte : L'utilisation du compte admin nico pour Renovate est une mauvaise pratique (permissions excessives).

Solution : - Création de l'utilisateur renovate-bot (ID 3, renovate-bot@ncls.ltd, non-admin) - Génération d'un PAT avec scopes minimaux : write:repository, write:issue, read:organization, read:misc - Secret Forgejo RENOVATE_TOKEN mis à jour (HTTP 204) - Collaborateur write sur homelab/infra (HTTP 204) - renovate.json5 mis à jour : - "platform": "forgejo" (était "gitea") - "gitAuthor": "Renovate Bot <renovate-bot@ncls.ltd>" - "reviewers": ["nico"]

4. Runner v6 → v12 (deadlock auto-update)¶

Chronologie : 1. Renovate ouvre PR #1 : bump runner code.forgejo.org/forgejo/runner:6 → :12 2. PR mergée → déclenche deploy.yml sur le push main 3. deploy.yml exécute pct exec 107 -- docker compose up -d pour 107-forge 4. Le runner exécute son propre job depuis l'intérieur de son container → docker compose up -d tue et recrée le container du runner → job tué en plein milieu 5. Runner arrêté. Redémarrage manuel : pct exec 107 -- bash -c "cd /opt/docker && docker compose up -d forgejo-runner"

Solution : Exclusion de 107-forge du workflow deploy.yml : - paths: trigger restreint à 1[0-6][0-9]-*/docker-compose.yml (exclut 107-*) - regex grep -oP mise à jour en conséquence - Entrée 107-forge) retirée du case

Procédure manuelle pour LXC 107 :

pct exec 107 -- bash -c 'cd /opt/docker && docker compose pull && docker compose up -d --remove-orphans'

Premiers PRs Renovate ouverts¶

État final stabilisé¶

LXC 107 — 192.168.1.107
├── forgejo:15          (port 3000/2222)  → healthy ✅
├── forgejo-runner:12   (label: ubuntu-latest, user: root)  → idle ✅
└── zot-linux-amd64     (port 5000, healthcheck disabled)  → up ✅

Pipeline GitOps complet :
  Renovate (cron 06h00) → PRs sur homelab/infra
  Merge → deploy.yml → pct exec NNN -- docker compose up -d
  107-forge : mise à jour MANUELLE uniquement