Configurare il runner CI remoto¶

Guida all'utilizzo dello script che fornisce a una macchina remota l'esecuzione di pipeline CI/CD gitrust tramite SSH + rsync + Dagger.

1. Ruolo della sceneggiatura¶

deployment/setup-remote-ci.sh (disponibile nel repository dei sorgenti gitrust) prepara un server di build remoto utilizzato dal lavoratore CI gitrust. Automatizza 6 passaggi:

1. Controlla la connettività SSH al corridore
2. Installa Docker (curl https://get.docker.com | sh) se è assente
3. Installa Dagger CLI (curl https://dl.dagger.io/dagger/install.sh | sh) se assente
4. Crea la directory di lavoro remota (CI_REMOTE_PATH)
5. Sincronizza il modulo deployment/ci-engine/ (modalità CI Easy) tramite rsync -az --delete
6. Test del fumo: visualizza "docker --version" e "dagger version".

Lo script è idempotente: riproduce senza danni, salta ciò che già esiste.

2. Quando usarlo¶

3. Architettura di destinazione¶

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

Il CI Worker gitrust (attività Tokyo nel file binario principale) non esegue Docker localmente: delega al runner tramite SSH. Ciò rende possibile isolare i carichi di lavoro più avidi di CPU/RAM (build Rust, Node, Docker) dal processo web gitrust.

4. Prerequisiti¶

Sulla macchina di esecuzione (dove lanciamo lo script)¶

Sul corridore lontano¶

5. Variabili d'ambiente previste (il .env)¶

Lo script genera un file .env il cui percorso viene passato come argomento, o per impostazione predefinita ../.env (relativo allo script, quindi <project_root>/.env).

Tabella delle variabili¶

Queste variabili sono le stesse di quelle lette da gitrust in fase di runtime. La centralizzazione in ".env" evita discrepanze tra provisioning e runtime.

Esempio minimo di .env (runner dedicato)¶

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

Esempio completo di .env che coesiste con la configurazione gitrust¶

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

Caso "Local runner" (non è necessario lo script)¶

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

In questo caso, installa Docker e Dagger direttamente sulla macchina gitrust, copia deployment/ci-engine/ in CI_ENGINE_PATH (predefinito /opt/gitrust/ci-engine) e vai avanti. Non eseguire setup-remote-ci.sh con CI_REMOTE_HOST=localhost.

6. Utilizzare¶

Dalla radice del progetto (impostazione predefinita)¶

cd /chemin/vers/gitrust

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

Con un file .env esplicito¶

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

Risultato previsto¶

==> 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. Cosa si trova sul corridore¶

Dopo l'esecuzione riuscita:

/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 (o equivalente) + socket /var/run/docker.sock - /usr/local/bin/pugnale

Gli spazi di lavoro della pipeline (checkout temporanei) vengono creati dal lavoratore CI gitrust in fase di runtime in CI_WORKSPACE_PATH (predefinito /tmp/gitrust-ci) — non da questo script.

8. Controlli successivi alla configurazione¶

Dalla macchina gitrust¶

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

Testare la pipeline tramite gitrust¶

Invio di un repository con un .gitrust-ci.yml minimo:

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

Quindi nell'interfaccia utente gitrust: scheda "Pipeline" → la pipeline deve passare allo stato "successo".

9. Aggiornamento dopo la modifica di "ci-engine/".¶

Il ci-engine/ sincronizzato non è “live-linked”: riproduci lo script dopo la modifica sul lato sorgente.

# 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 elimina i file lato runner che non esistono più localmente: garantisce la coerenza.

10. Risoluzione dei problemi¶

11. Sicurezza¶

• Il runner CI esegue codice arbitrario proveniente da repository ospitati. Mai collocarlo con segreti sensibili (prod PG, chiavi prod).
• Isola rete: blocca l'accesso in uscita dal runner alla LAN privata (è necessario solo l'accesso a Internet per docker pull).
• Limita sudo NOPASSWD al minimo indispensabile sul runner (idealmente: solo per i comandi docker e apt).
• Rotazione regolare della chiave SSH CI_REMOTE_SSH_KEY. Revocarlo in ~/.ssh/authorized_keys dal lato runner in caso di sospetto.
• Il corridore non deve essere in grado di connettersi tramite SSH alla macchina gitrust (unidirezionale).