From ecb7a44c3ca8999945489fc8837badc8391605e9 Mon Sep 17 00:00:00 2001
From: Corentin JOGUET <corentin@acadenice.fr>
Date: Thu, 7 May 2026 13:49:19 +0200
Subject: [PATCH] ops(infra): add Forgejo Actions Runner skeleton

- infra/forgejo-runner/compose.yml : runner v6.5.0 avec auto-register
- infra/forgejo-runner/.env.example : variables registration
- infra/forgejo-runner/README.md : setup + usage + securite + troubleshooting
- infra/README.md : index

Le runner est OPTIONNEL et a deployer separement quand on veut activer le CI
sur git.acadenice.com. Tant que pas deploye, les workflows GitHub Actions
restent actifs sur github.com/AcadeNice/wiki (mirror).
---
 infra/README.md                   |  15 +++++
 infra/forgejo-runner/.env.example |  19 ++++++
 infra/forgejo-runner/README.md    | 107 ++++++++++++++++++++++++++++++
 infra/forgejo-runner/compose.yml  |  43 ++++++++++++
 4 files changed, 184 insertions(+)
 create mode 100644 infra/README.md
 create mode 100644 infra/forgejo-runner/.env.example
 create mode 100644 infra/forgejo-runner/README.md
 create mode 100644 infra/forgejo-runner/compose.yml

diff --git a/infra/README.md b/infra/README.md
new file mode 100644
index 0000000..d2eca40
--- /dev/null
+++ b/infra/README.md
@@ -0,0 +1,15 @@
+# Infra
+
+Infrastructure auxiliaire (hors stack applicative principale).
+
+## Sous-dossiers
+
+| Dossier | Role |
+|---------|------|
+| `forgejo-runner/` | Runner CI/CD pour git.acadenice.com (Forgejo Actions) |
+| `traefik/` (a venir) | Configuration Traefik si versionnee |
+| `monitoring/` (a venir Phase 3) | Prometheus + Grafana + Loki |
+
+## Deploiement
+
+Chaque sous-dossier est independant et auto-suffisant. Voir le `README.md` du sous-dossier concerne pour le setup.
diff --git a/infra/forgejo-runner/.env.example b/infra/forgejo-runner/.env.example
new file mode 100644
index 0000000..06c6ac0
--- /dev/null
+++ b/infra/forgejo-runner/.env.example
@@ -0,0 +1,19 @@
+# Forgejo Actions Runner — variables d'environnement
+# Copier vers .env et remplir.
+
+# URL Forgejo
+FORGEJO_INSTANCE_URL=https://git.acadenice.com
+
+# Token de registration (a recuperer 1x via API ou UI Forgejo)
+# UI : git.acadenice.com → Site Administration → Actions → Runners → Create runner token
+# API : POST /api/v1/orgs/AcadeNice/actions/runners/registration-token
+# Le token est valide pendant 30 min apres generation.
+FORGEJO_RUNNER_REGISTRATION_TOKEN=
+
+# Nom du runner (visible dans Forgejo UI)
+FORGEJO_RUNNER_NAME=runner-acadenice-01
+
+# Labels — workflows utilisent runs-on: <label>
+# Les standards : docker, ubuntu-latest, ubuntu-22.04
+# Custom : acadenice (pour les jobs Acadenice-specifiques)
+FORGEJO_RUNNER_LABELS=docker,ubuntu-latest,ubuntu-22.04,acadenice
diff --git a/infra/forgejo-runner/README.md b/infra/forgejo-runner/README.md
new file mode 100644
index 0000000..79f46dc
--- /dev/null
+++ b/infra/forgejo-runner/README.md
@@ -0,0 +1,107 @@
+# Forgejo Actions Runner
+
+Runner CI/CD pour les workflows GitHub Actions execute sur **git.acadenice.com**.
+
+## Architecture
+
+```
+git.acadenice.com (Forgejo 10.0.3)
+        ↓ poll long-running connection
+   Forgejo Runner (ce service)
+        ↓ docker.sock
+     Docker host
+        ↓ run jobs
+     Containers ephemeres (build, test, deploy)
+```
+
+## Prerequis
+
+- Docker + Docker Compose v2 sur le host
+- Acces sortant vers `git.acadenice.com`
+- Acces a `docker.sock` (mount /var/run/docker.sock)
+- Pour les jobs avec containers : Docker daemon avec privileges suffisants
+
+## Setup (premiere fois)
+
+### 1. Recuperer un token de registration
+
+Option A — via API (organizations) :
+```bash
+curl -sf -H "Authorization: token <TON_TOKEN_ADMIN>" \
+  https://git.acadenice.com/api/v1/orgs/AcadeNice/actions/runners/registration-token \
+  | jq -r '.token'
+```
+
+Option B — via UI Forgejo (recommande pour debutant) :
+- `git.acadenice.com` → Login → Site Administration → Actions → Runners → Create new runner
+- Copier le token affiche
+
+Le token expire 30 min apres generation.
+
+### 2. Configurer .env
+
+```bash
+cd infra/forgejo-runner
+cp .env.example .env
+# editer .env :
+# FORGEJO_RUNNER_REGISTRATION_TOKEN=<token genere>
+```
+
+### 3. Up
+
+```bash
+docker compose up -d
+docker compose logs -f
+# Attendre "Runner registered successfully"
+```
+
+### 4. Verifier sur Forgejo
+
+`git.acadenice.com` → Site Administration → Actions → Runners → le runner doit apparaitre comme `Online`.
+
+## Apres setup — usage
+
+Les workflows `.github/workflows/*.yml` ou `.forgejo/workflows/*.yml` du repo `AcadeNice/Wiki` se declenchent automatiquement apres push.
+
+Le runner pull les jobs et les execute en containers Docker.
+
+## Workflows compatibles
+
+Forgejo Actions est **95% compatible** GitHub Actions syntax. La majorite des workflows GitHub marchent tels quels.
+
+Differences notables :
+- `actions/checkout@v4` : marche, mais resolu via le marketplace **gitea/actions** (configure auto par le runner)
+- Secrets : a configurer dans Forgejo UI au niveau repo OU org
+- `GITHUB_TOKEN` : remplace par `GITEA_TOKEN` (ou alias compatible)
+- Pas de support `actions/setup-node@v4` directement — il faut un runner avec Node pre-installe OU utiliser une image custom
+
+Recommandation : pinner les actions tierces sur des SHA commit pour eviter les surprises.
+
+## Maintenance
+
+| Tache | Frequence |
+|-------|-----------|
+| Bump runner version | Tous les 2-3 mois (cf [releases](https://code.forgejo.org/forgejo/runner)) |
+| Cleanup docker images cache | Mensuel (`docker system prune -a` apres backup) |
+| Verifier logs `docker compose logs --tail=100` | Hebdomadaire |
+| Backup runner data volume | Quotidien (config seulement, pas de state critique) |
+
+## Securite
+
+- **docker.sock mount** = privilege root sur le host. Le runner peut creer/supprimer n'importe quel container. **Ne pas heberger sur un host sensible.**
+- Recommandation : VPS dedie pour le runner (5€/mois Hetzner CPX11).
+- Si VPS partage : utiliser `docker-in-docker` (DinD) au lieu de docker.sock mount.
+
+## Troubleshooting
+
+| Symptome | Cause probable | Fix |
+|----------|---------------|-----|
+| Runner "Offline" sur Forgejo | Token expire ou network | Regenerer token, restart container |
+| Job stuck en pending | Pas de runner disponible avec les labels demandes | Verifier `runs-on` du workflow vs labels du runner |
+| `permission denied` sur docker.sock | User dans le container n'est pas root | Verifier `user: "0:0"` dans compose |
+| Build lent | Pas de cache Docker | Activer BuildKit avec `DOCKER_BUILDKIT=1` |
+
+## References
+
+- [Forgejo Actions docs](https://forgejo.org/docs/latest/admin/actions/)
+- [act_runner project](https://code.forgejo.org/forgejo/runner)
diff --git a/infra/forgejo-runner/compose.yml b/infra/forgejo-runner/compose.yml
new file mode 100644
index 0000000..400e29b
--- /dev/null
+++ b/infra/forgejo-runner/compose.yml
@@ -0,0 +1,43 @@
+name: forgejo-runner
+
+# Forgejo Actions Runner pour git.acadenice.com
+# Documentation : https://forgejo.org/docs/latest/admin/actions/
+
+services:
+  runner:
+    image: code.forgejo.org/forgejo/runner:6.5.0
+    restart: unless-stopped
+    user: "0:0"
+    environment:
+      FORGEJO_INSTANCE_URL: ${FORGEJO_INSTANCE_URL:-https://git.acadenice.com}
+      FORGEJO_RUNNER_REGISTRATION_TOKEN: ${FORGEJO_RUNNER_REGISTRATION_TOKEN}
+      FORGEJO_RUNNER_NAME: ${FORGEJO_RUNNER_NAME:-runner-acadenice-01}
+      # Labels permettent aux workflows de cibler ce runner avec `runs-on: <label>`
+      FORGEJO_RUNNER_LABELS: ${FORGEJO_RUNNER_LABELS:-docker,ubuntu-latest,ubuntu-22.04,acadenice}
+    volumes:
+      - runner-data:/data
+      - /var/run/docker.sock:/var/run/docker.sock
+    command:
+      - /bin/sh
+      - -c
+      - |
+        set -e
+        if [ ! -f /data/.runner ]; then
+          echo "First boot — registering runner..."
+          forgejo-runner register \
+            --no-interactive \
+            --instance "$$FORGEJO_INSTANCE_URL" \
+            --name "$$FORGEJO_RUNNER_NAME" \
+            --token "$$FORGEJO_RUNNER_REGISTRATION_TOKEN" \
+            --labels "$$FORGEJO_RUNNER_LABELS"
+        fi
+        exec forgejo-runner daemon
+    networks:
+      - default
+
+volumes:
+  runner-data:
+
+networks:
+  default:
+    name: forgejo-runner