Susan

Poste unique

Disponible

Cette configuration lance le tableau de bord et l’opérateur avec Docker Compose sur votre ordinateur. L’opérateur emploie son moteur docker : il démarre chaque run (une exécution d’un workflow ; voir le glossaire) dans un conteneur de votre moteur Docker, au lieu d’un Job Kubernetes. Les runs avancent tant que l’ordinateur et Docker sont allumés.

Avant de commencer

Installer la suite

curl -fsSL https://heysusan.dev/install.sh | sh

Le script écrit un fichier Compose et ses réglages dans le dossier .susan de votre dossier personnel (posez SUSAN_HOME pour en choisir un autre), télécharge les trois images (nexus-runner, nexus-operator, nexus-dashboard), démarre la suite et attend que le tableau de bord réponde sur http://localhost:8090. Il crée une fois la clé qui signe les jetons des runs et le jeton de l’API de l’opérateur, dans des volumes Docker. Relancé, il met les images à jour et garde vos données. SUSAN_VERSION choisit l’étiquette des images.

Le conteneur de l’opérateur lit la socket Docker de votre ordinateur pour lancer les runs : il détient donc les mêmes droits que Docker sur cet ordinateur. Lisez le script avant de le lancer.

Isolation par gVisor

Chaque conteneur de run tourne sans capacités Linux et sans élévation de privilèges. Sous Linux avec Docker Engine, le script le lance aussi sous gVisor, par défaut : un noyau en espace utilisateur qui intercepte ses appels système, si bien que le code lancé par un agent ne parle plus directement au noyau de votre ordinateur.

Le script télécharge gVisor depuis son dépôt de versions, vérifie le téléchargement par sa somme SHA-512, installe runsc dans /usr/local/bin et le déclare à Docker par runsc install, puis fait relire ses réglages à Docker (signal SIGHUP) sans arrêter vos conteneurs. sudo demande votre mot de passe à cette étape. Si runsc est déjà déclaré, le script n’installe rien. Avant de démarrer la suite, il lance un conteneur sous runsc pour vérifier que Docker peut s’en servir. La fin de sa sortie contient The containers of the runs run under gVisor (runsc).

Sous Ubuntu avec Docker installé par snap, Docker tourne confiné et ne voit pas /usr/local/bin. Le script installe alors gVisor dans /var/snap/docker/common/gvisor et le déclare dans /var/snap/docker/current/config/daemon.json. Si le confinement empêche malgré tout Docker de lancer runsc, le conteneur d’essai échoue et le script en donne la cause : installez alors Docker Engine depuis le dépôt de Docker à la place du snap.

gVisor a besoin de pkill, de sha512sum, et de zstd ou de bzip2. S’il en manque un, le script installe son paquet avec le gestionnaire de paquets de votre distribution (apt-get, dnf, yum, zypper, pacman, apk ou xbps-install), et nomme les paquets avant de le faire. Il obtient les droits root par sudo, ou par doas quand sudo est absent, comme sous Alpine. Pour choisir la commande, posez SUSAN_SUDO :

curl -fsSL https://heysusan.dev/install.sh | SUSAN_SUDO=doas sh

Sans persist dans /etc/doas.conf, doas demande votre mot de passe à chaque étape, jusqu’à quatre fois.

Relancé, le script garde le choix de la première installation. Si Docker ne déclare plus runsc, l’opérateur ne démarre pas : aucun run ne part sans l’isolation choisie. gVisor ralentit les commandes qui font beaucoup d’opérations sur les fichiers, comme npm install ou composer install.

Avec Docker Desktop (macOS, ou Windows sans WSL2), Docker tourne dans sa propre machine virtuelle, où le script ne peut pas ajouter gVisor : les runs utilisent le runtime par défaut de Docker, et le script le signale. Sous Windows, installez Docker Engine dans une distribution Ubuntu de WSL2 et lancez la commande dans cette distribution. Avec Docker en mode rootless, ou pour dépanner, installez sans gVisor :

curl -fsSL https://heysusan.dev/install.sh | SUSAN_GVISOR=0 sh

Construire depuis le dépôt

Depuis la racine d’un clone, docker compose up --build -d construit les trois images depuis les sources et démarre la même suite. Vérifiez les services avec docker compose ps -a : operator et dashboard sont running, runner et keys sont sortis avec le code 0. Dans ce mode, NEXUS_DASHBOARD_PORT règle le port, et NEXUS_PROJECTS liste les projets, séparés par des virgules (par défaut, un seul projet, local).

Brancher une forge (facultatif)

Sans forge, les runs, les questions et les réponses fonctionnent, et le tableau de bord ne suit aucune pull request. Pour suivre les pull requests d’une forge Forgejo ou Gitea, donnez son adresse, un jeton et le secret de ses webhooks à l’installation :

curl -fsSL https://heysusan.dev/install.sh | FORGEJO_URL=https://forge.example FORGEJO_TOKEN=<votre jeton> FORGEJO_WEBHOOK_SECRET=<secret> sh

Les mêmes variables s’appliquent à docker compose up depuis le dépôt. Susan est testée avec Forgejo ; Gitea sert les mêmes routes d’API et la même signature de webhook d’après sa documentation, sans essai sur une instance réelle pour l’instant. GitHub et GitLab ne sont pas encore pris en charge.

Lancer un premier workflow

Depuis un clone du dépôt, deploy/smoke-test.sh joue une demande complète par l’API du tableau de bord. Il crée un item (une unité de travail que suit le tableau de bord), lance un run du workflow ask, répond à la question que pose le run et attend la fin du run.

NEXUS_DASHBOARD_URL=http://127.0.0.1:8090 deploy/smoke-test.sh local

Le script se termine par une ligne RÉUSSI qui nomme l’item et les deux runs. Suivez-les sur http://localhost:8090.

Servir vos projets en HTTPS avec le proxy local

proxyctl fait tourner un reverse proxy Traefik sur le port 443 pour tous les projets de votre ordinateur, conteneurisés ou non. Les domaines finissent en .localhost, que systemd-resolved résout en 127.0.0.1 sans DNS ni entrée dans /etc/hosts. Les certificats viennent de mkcert.

sudo apt install mkcert && mkcert -install
make -C cmd/proxyctl install
proxyctl up

Pour exposer un service Docker, rattachez-le au réseau externe proxy avec deux labels Traefik, puis déclarez son domaine une fois :

proxyctl domains add '*.monprojet.localhost'

Pour un service qui tourne hors de Docker, comme un serveur de développement sur le port 8001 :

proxyctl routes add web.monprojet.localhost 8001

proxyctl routes liste chaque route avec son backend et sa santé. La référence complète est dans cmd/proxyctl/README.md.

Arrêter la suite

Les conteneurs des runs ne sont pas des services Compose : docker compose down ne les arrête pas. Attendez la fin des runs, ou retirez leurs conteneurs, puis arrêtez la suite :

docker rm -f $(docker ps -aq --filter label=nexus.dashboard/run)
docker compose down

Les volumes restent : les runs, la base du tableau de bord et les clés se retrouvent au lancement suivant. Ajoutez -v pour tout effacer.

Limites de cette configuration

Sur un clusterSur un poste
nexus-collector garde les messages d’un run dans un journal sur disque et les livre après la fin du pod.Pas de collecteur. Si l’opérateur ne répond pas, une question échoue après 10 secondes, et un run dont le conteneur disparaît passe à lost.
Le flux du run et l’API de l’opérateur passent en TLS mutuel.En clair sur le réseau Docker nexus-local, qui ne quitte pas l’ordinateur.
Une politique réseau borne ce que le pod d’un run peut joindre.Le conteneur d’un run joint tout ce que joint votre ordinateur.
Kueue admet les runs sous un plafond global du cluster.Seuls les plafonds de l’opérateur s’appliquent (NEXUS_OPERATOR_LIMIT_GLOBAL, NEXUS_OPERATOR_LIMIT_PER_PROJECT).
Un run peut lancer les services que décrit le fichier Compose de son projet.Une demande de run qui porte ces services est rejetée.

Docker relance l’opérateur et le tableau de bord après un redémarrage de l’ordinateur, dans les deux modes (restart: unless-stopped).

Le guide détaillé est docs/lancer-un-run-en-local.md.