Konfigurieren Sie den Remote-CI-Runner¶

Anleitung zur Verwendung des Skripts, das einen Remote-Computer für die Ausführung von Gitrust-CI/CD-Pipelines über SSH + rsync + Dagger bereitstellt.

1. Rolle des Skripts¶

„deployment/setup-remote-ci.sh“ (verfügbar im Gitrust-Quell-Repository) bereitet einen Remote-Build-Server vor, der vom Gitrust-CI-Worker verwendet wird. Es automatisiert 6 Schritte:

1. Überprüft die SSH-Konnektivität zum Runner
2. Installieren Sie Docker (curl https://get.docker.com | sh), falls es nicht vorhanden ist
3. Installiert Dagger CLI (curl https://dl.dagger.io/dagger/install.sh | sh), falls nicht vorhanden
4. Erstellt das Remote-Arbeitsverzeichnis („CI_REMOTE_PATH“)
5. Synchronisieren Sie das Modul „deployment/ci-engine/“ (CI Easy-Modus) über „rsync -az --delete“.
6. Rauchtest: Zeigt „docker --version“ und „dagger version“ an

Das Skript ist idempotent: Es wird ohne Schaden wiederholt und überspringt, was bereits vorhanden ist.

2. Wann sollte man es verwenden?¶

3. Zielarchitektur¶

+---------------------+        SSH + rsync        +-----------------------+
|  Gitrust (web+SSH)  |---------------------------|  CI Runner (distant)  |
|  <your-server-ip>   |  CI_REMOTE_HOST/USER/KEY  |  <ci-runner-ip>       |
|                     |                           |                       |
|  Worker CI Tokio    |   push .gitrust-ci.yml    |  /opt/gitrust-ci/     |
|  (dans gitrust.bin) |   + code source checkout  |   ├── ci-engine/      |
|                     |                           |   └── workspaces/     |
|                     |   dagger call ...         |                       |
|                     |                           |  Docker + Dagger CLI  |
+---------------------+                           +-----------------------+

Der Gitrust-CI-Worker (Tokio-Task in der Hauptbinärdatei) führt Docker nicht lokal aus – er delegiert über SSH an den Runner. Dadurch ist es möglich, gierige CPU-/RAM-Workloads (Rust-, Node-, Docker-Builds) vom Gitrust-Webprozess zu isolieren.

4. Voraussetzungen¶

Auf der Ausführungsmaschine (wo wir das Skript starten)¶

Auf dem fernen Läufer¶

5. Erwartete Umgebungsvariablen (die „.env“)¶

Das Skript gibt eine „.env“-Datei an, deren Pfad als Argument übergeben wird, oder standardmäßig „../.env“ (relativ zum Skript, daher „/.env“).

Variablentabelle¶

Diese Variablen sind die gleichen wie die, die Gitrust zur Laufzeit liest. Durch die Zentralisierung in „.env“ werden Diskrepanzen zwischen Bereitstellung und Laufzeit vermieden.

Minimales Beispiel für „.env“ (dedizierter Läufer)¶

# --- CI runner distant ---
CI_REMOTE_HOST=<ci-runner-ip>
CI_REMOTE_USER=ci-runner
CI_REMOTE_SSH_PORT=22
CI_REMOTE_PATH=/opt/gitrust-ci
CI_REMOTE_SSH_KEY=/home/gitrust/.ssh/ci_runner_ed25519

Vollständiges „.env“-Beispiel, das mit der Gitrust-Konfiguration koexistiert¶

DATABASE_URL=postgres://...
JWT_SECRET=...
# ... (voir .env.example pour le reste)

# --- CI/CD (lu par gitrust ET par setup-remote-ci.sh) ---
CI_ENABLED=true
CI_MAX_CONCURRENT=4
CI_REMOTE_HOST=ci-runner.internal
CI_REMOTE_USER=ci-runner
CI_REMOTE_PATH=/opt/gitrust-ci
CI_REMOTE_SSH_KEY=/opt/gitrust/data/ci_runner_key

Fall „Lokaler Läufer“ (das Skript ist nicht erforderlich)¶

CI_REMOTE_HOST=localhost
# Les autres CI_REMOTE_* sont ignorés

In diesem Fall installieren Sie Docker und Dagger direkt auf der Gitrust-Maschine, kopieren Sie „deployment/ci-engine/“ nach „CI_ENGINE_PATH“ (Standard „/opt/gitrust/ci-engine“) und fahren Sie fort. Führen Sie „setup-remote-ci.sh“ nicht mit „CI_REMOTE_HOST=localhost“ aus.

6. Verwendung¶

Aus dem Projektstammverzeichnis (Standard)¶

cd /chemin/vers/gitrust

# .env a la racine (défaut) :
./deployment/setup-remote-ci.sh

Mit einer expliziten „.env“.¶

./deployment/setup-remote-ci.sh /chemin/vers/mon.env
# Utile si vous avez .env.production, .env.staging, etc.
./deployment/setup-remote-ci.sh .env.production

Erwartete Ausgabe¶

==> Configuration :
    Serveur  : ci-runner@<ci-runner-ip>
    Port SSH : 22
    Chemin   : /opt/gitrust-ci

==> [1/6] Vérification de la connectivité SSH...
SSH OK
    OK
==> [2/6] Vérification de Docker...
    Docker déjà installé
==> [3/6] Vérification de Dagger CLI...
    Installation de Dagger CLI...
    Dagger installé
==> [4/6] Création du répertoire distant...
    /opt/gitrust-ci créé
==> [5/6] Synchronisation du ci-engine...
sending incremental file list
ci-engine/
ci-engine/profiles/
...
    ci-engine synchronisé vers /opt/gitrust-ci/ci-engine/
==> [6/6] Smoke test...
    Versions distantes :
Docker version 28.0.1, build abcd123
dagger v0.19.2 (linux/amd64)

==> Setup terminé. Le serveur ci-runner@<ci-runner-ip> est prêt pour l'exécution CI.
    Pensez à configurer CI_EXECUTION_MODE=remote dans votre .env

7. Was befindet sich auf dem Läufer?¶

Nach erfolgreicher Ausführung:

/opt/gitrust-ci/                    <- CI_REMOTE_PATH
└── ci-engine/                      <- synchronisé depuis deployment/ci-engine/
    ├── README.md
    └── profiles/                   <- templates par stack (Python, Node, Rust, ...)

Plus, installés globalement : - /usr/bin/docker (oder gleichwertig) + Socket /var/run/docker.sock - /usr/local/bin/dagger

Pipeline-Arbeitsbereiche (temporäre Checkouts) werden vom Gitrust-CI-Worker zur Laufzeit unter „CI_WORKSPACE_PATH“ (Standard „/tmp/gitrust-ci“) erstellt – nicht von diesem Skript.

8. Kontrollen nach der Einrichtung¶

Von der Gitrust-Maschine¶

# Source le .env
set -a; source .env.production; set +a

# 1. SSH direct (doit passer sans prompt)
ssh -p ${CI_REMOTE_SSH_PORT:-22} \
    ${CI_REMOTE_SSH_KEY:+-i $CI_REMOTE_SSH_KEY} \
    $CI_REMOTE_USER@$CI_REMOTE_HOST 'docker info && dagger version'

# 2. Rsync round-trip (lecture/écriture sur CI_REMOTE_PATH)
echo "test" | ssh $CI_REMOTE_USER@$CI_REMOTE_HOST \
    "cat > $CI_REMOTE_PATH/.gitrust-test && cat $CI_REMOTE_PATH/.gitrust-test && rm $CI_REMOTE_PATH/.gitrust-test"
# Attendu : "test"

Testpipeline über Gitrust¶

Ein Repository mit einer minimalen Datei „.gitrust-ci.yml“ pushen:

# .gitrust-ci.yml
version: 1
pipeline:
  - name: smoke
    image: alpine:3
    run: echo "CI runner OK"

Dann in der Gitrust-Benutzeroberfläche: Registerkarte „Pipelines“ → die Pipeline muss in den Status „Erfolg“ wechseln.

9. Update nach Änderung von „ci-engine/“.¶

Die synchronisierte „ci-engine/“ ist nicht „live-linked“: Spielen Sie das Skript nach der Änderung auf der Quellseite erneut ab.

# Modifier deployment/ci-engine/profiles/*.py ou similaire
./deployment/setup-remote-ci.sh
# Les étapes 2-3 sont skip (déjà installés), seule l'étape 5 refait le rsync

„rsync -az --delete“ löscht runner-seitige Dateien, die lokal nicht mehr vorhanden sind – sorgt für Konsistenz.

10. Fehlerbehebung¶

11. Sicherheit¶

• Der CI-Runner führt beliebigen Code aus, der aus gehosteten Repositorys stammt. Niemals es mit vertraulichen Geheimnissen (Produkt-PG, Produktschlüssel) zusammenführen.
• Netzwerk isolieren: Blockieren Sie den ausgehenden Zugriff vom Läufer auf das private LAN (nur Internetzugang für „Docker Pull“ ist erforderlich).
• Beschränken Sie „sudo NOPASSWD“ auf dem Runner auf das strikte Minimum (idealerweise: nur für die Befehle „docker“ und „apt“).
• Regelmäßige Rotation des SSH-Schlüssels „CI_REMOTE_SSH_KEY“. Im Verdachtsfall auf der Läuferseite in „~/.ssh/authorized_keys“ widerrufen.
• Der Läufer darf nicht in der Lage sein, sich über SSH mit der Gitrust-Maschine zu verbinden (unidirektional).