@yunuseon/kayra 0.0.0-stage → 0.5.0

package/cli/dist/interpret.js

@@ -0,0 +1,98 @@
+import { spawn } from "node:child_process";
+import { text } from "node:stream/consumers";
+const spawned = async (argv, streams, env = {}) => {
+    const [program, ...args] = argv;
+    const child = spawn(program, args, {
+        env: { ...process.env, ...env },
+        stdio: [
+            "inherit",
+            streams.stdout === "show" ? "inherit" : streams.stdout === "capture" ? "pipe" : "ignore",
+            streams.stderr === "show" ? "inherit" : "pipe",
+        ],
+    });
+    const stdout = child.stdout === null ? Promise.resolve("") : text(child.stdout);
+    const stderr = child.stderr === null ? Promise.resolve("") : text(child.stderr);
+    const exit = await new Promise((resolve) => {
+        child.on("error", resolve);
+        child.on("close", (code) => {
+            resolve(code ?? 1);
+        });
+    });
+    return exit instanceof Error
+        ? { code: 127, stdout: "", stderr: exit.message }
+        : { code: exit, stdout: await stdout, stderr: await stderr };
+};
+/** A command's stdout, for kayra to read; its stderr reaches the operator unless captured too. */
+export const capture = (argv, stderr = "show", env = {}) => spawned(argv, { stdout: "capture", stderr }, env);
+const answer = (probe) => spawned(probe.kind === "on-path" ? ["sh", "-c", 'command -v "$1"', "sh", probe.program] : probe.argv, { stdout: "discard", stderr: "capture" }, probe.kind === "exits-zero" ? probe.env : {});
+/** Each query's answer in place of it, as `$(…)` would: one word, or split into many. Undefined if one failed. */
+const resolve = async (argv, io) => {
+    const words = await Promise.all(argv.map(async (value) => {
+        if (typeof value === "string")
+            return [value];
+        const exit = await capture(value.argv, "show", value.env);
+        if (exit.code !== 0) {
+            io.err(`kayra: ${value.argv.join(" ")} failed (exit ${String(exit.code)})`);
+            return undefined;
+        }
+        const output = exit.stdout.replace(/\n+$/, "");
+        return value.words === "one" ? [output] : output.split(/\s+/).filter((word) => word !== "");
+    }));
+    const [program, ...rest] = words.flatMap((word) => word ?? []);
+    return words.includes(undefined) || program === undefined ? undefined : [program, ...rest];
+};
+const lines = (text) => text
+    .trimEnd()
+    .split("\n")
+    .filter((line) => line !== "");
+const goOn = { failed: false, stopped: false };
+const check = async (step, io) => {
+    const exit = await answer(step.probe);
+    const hint = step.hint === undefined ? [] : [`    → ${step.hint}`];
+    if (step.onFailure === "stop") {
+        if (exit.code === 0)
+            return goOn;
+        [...lines(exit.stderr), ...hint].forEach(io.err);
+        return { failed: true, stopped: true };
+    }
+    if (exit.code === 0) {
+        io.out(`ok    ${step.label}`);
+        return goOn;
+    }
+    [`FAIL  ${step.label}`, ...lines(exit.stderr).map((line) => `    ${line}`), ...hint].forEach(io.out);
+    return { failed: true, stopped: false };
+};
+const perform = async (step, io) => {
+    switch (step.kind) {
+        case "run": {
+            const argv = await resolve(step.argv, io);
+            if (argv === undefined)
+                return { failed: true, stopped: true };
+            const exit = await spawned(argv, { stdout: step.stdout, stderr: "show" }, step.env);
+            return exit.code === 0 ? goOn : { failed: true, stopped: true };
+        }
+        case "check":
+            return check(step, io);
+        case "confirm": {
+            const typed = await io.ask(step.prompt);
+            if (typed === step.expect)
+                return goOn;
+            io.out("Aborted.");
+            return { failed: false, stopped: true };
+        }
+        case "note":
+            io.out(step.text);
+            return goOn;
+    }
+};
+/** Runs a plan step by step, until it ends or a step stops it. True if nothing failed. */
+export const interpret = async (plan, io) => {
+    const outcome = await plan.reduce(async (previous, step) => {
+        const so = await previous;
+        if (so.stopped)
+            return so;
+        const next = await perform(step, io);
+        return { failures: so.failures + (next.failed ? 1 : 0), stopped: next.stopped };
+    }, Promise.resolve({ failures: 0, stopped: false }));
+    return outcome.failures === 0;
+};

package/cli/dist/load.js

@@ -0,0 +1,49 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fleetRoot, serverDir, serverName, within } from "./brand.js";
+import { parseServer } from "./fleet.js";
+import { all, err, map, ok } from "./result.js";
+/** The fleet is the nearest directory, from `from` upwards, with a servers/defaults.yml. */
+export const findFleetRoot = (from) => {
+    if (existsSync(join(from, "servers", "defaults.yml")))
+        return ok(fleetRoot(from));
+    const parent = within(from, "..");
+    return parent === from
+        ? err("no fleet here: no servers/defaults.yml in this directory or above it")
+        : findFleetRoot(parent);
+};
+const text = (path) => (existsSync(path) ? readFileSync(path, "utf8") : undefined);
+const stacks = (dir) => existsSync(join(dir, "stacks"))
+    ? readdirSync(join(dir, "stacks"))
+        .toSorted()
+        .flatMap((stack) => text(join(dir, "stacks", stack, "compose.yaml")) ?? [])
+    : [];
+const appValues = (dir) => existsSync(join(dir, "apps"))
+    ? readdirSync(join(dir, "apps"))
+        .filter((file) => file.endsWith(".yml"))
+        .toSorted()
+        .map((file) => ({ file, text: readFileSync(join(dir, "apps", file), "utf8") }))
+    : [];
+const readServer = (root, entry) => {
+    const name = serverName(entry);
+    if (!name.ok)
+        return err(`servers/${entry}: ${name.error}`);
+    const dir = serverDir(root, name.value);
+    const server = parseServer({
+        name: name.value,
+        dir,
+        descriptor: readFileSync(join(dir, "server.yml"), "utf8"),
+        vars: text(join(dir, "vars.yml")),
+        secrets: text(join(dir, "secrets.yml")),
+        inventory: text(join(dir, "inventory.ini")),
+        terraform: existsSync(join(dir, "terraform")),
+        stacks: stacks(dir),
+        appValues: appValues(dir),
+    });
+    return server.ok ? server : err(`servers/${entry}/server.yml: ${server.error}`);
+};
+export const loadFleet = (root) => map(all(readdirSync(join(root, "servers"), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(root, "servers", entry.name, "server.yml")))
+    .map((entry) => entry.name)
+    .toSorted()
+    .map((entry) => readServer(root, entry))), (servers) => ({ root, servers }));

package/cli/dist/main.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { run } from "@optique/run";
+import { readFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { absolutePath, kayraRoot, kayraVersion, within } from "./brand.js";
+import { parser } from "./cli.js";
+import { doctor } from "./commands/doctor.js";
+import * as server from "./commands/server.js";
+import { status } from "./commands/status.js";
+import { serverNamed } from "./fleet.js";
+import { interpret } from "./interpret.js";
+import { findFleetRoot, loadFleet } from "./load.js";
+import { render } from "./plan.js";
+import { flatMap, ok } from "./result.js";
+const here = absolutePath(process.cwd());
+const engine = absolutePath(import.meta.dirname);
+if (!here.ok || !engine.ok)
+    throw new Error("node reported a relative path");
+const kayra = kayraRoot(within(engine.value, "..", ".."));
+const manifest = JSON.parse(readFileSync(within(kayra, "package.json"), "utf8"));
+const version = kayraVersion(typeof manifest === "object" && manifest !== null && "version" in manifest ? manifest.version : undefined);
+if (!version.ok)
+    throw new Error(`kayra's package.json: ${version.error}`);
+const onServer = (on, target, command) => {
+    switch (command.name) {
+        case "up":
+            return server.up(on, target);
+        case "provision":
+            return server.provision(on, target);
+        case "deploy":
+            return server.deploy(on, target);
+        case "setup":
+            return server.setup(on, target);
+        case "apps":
+            return server.apps(on, target);
+        case "hosts":
+            return server.hosts(on, target);
+        case "ssh":
+            return server.ssh(target);
+        case "down":
+            return server.down(target);
+        case "adopt":
+            return server.adopt(on, target);
+        case "backup test":
+            return server.backupTest(on, target);
+    }
+};
+const plan = (fleet, command) => {
+    const on = { kayra, version: version.value, fleet: fleet.root };
+    if (command.name === "doctor")
+        return ok(doctor(fleet, kayra));
+    if (command.name === "certs")
+        return server.certsFor(on, command.domain, command.subdomains);
+    if (command.name === "app purge")
+        return flatMap(serverNamed(fleet, command.server), (target) => server.appPurge(on, target, command.app));
+    return flatMap(serverNamed(fleet, command.server), (target) => onServer(on, target, command));
+};
+const io = {
+    out: (line) => {
+        console.log(line);
+    },
+    err: (line) => {
+        console.error(line);
+    },
+    ask: async (prompt) => {
+        const terminal = createInterface({ input: process.stdin, output: process.stderr });
+        const answer = await terminal.question(prompt);
+        terminal.close();
+        return answer;
+    },
+};
+const fail = (message) => {
+    console.error(`kayra: ${message}`);
+    process.exit(1);
+};
+const fleet = flatMap(findFleetRoot(here.value), loadFleet);
+if (!fleet.ok)
+    fail(fleet.error);
+else {
+    const args = run(parser(fleet.value), { programName: "kayra", help: "both", completion: "both" });
+    if (args.command.name === "status") {
+        (await status(fleet.value)).forEach(io.out);
+    }
+    else {
+        const steps = plan(fleet.value, args.command);
+        if (!steps.ok)
+            fail(steps.error);
+        else if (args.dryRun)
+            render(steps.value).forEach(io.out);
+        // eslint-disable-next-line functional/immutable-data -- the exit status; process.exit() could cut piped output short
+        else
+            process.exitCode = (await interpret(steps.value, io)) ? 0 : 1;
+    }
+}

package/cli/dist/plan.js

@@ -0,0 +1,31 @@
+export const run = (argv, env = {}) => ({
+    kind: "run",
+    argv,
+    env,
+    stdout: "show",
+});
+const quote = (word) => (/^[\w@%+=:,./~-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`);
+export const shell = (argv) => argv.map(quote).join(" ");
+const assignments = (env = {}) => Object.entries(env)
+    .map(([key, value]) => `${key}=${quote(value)} `)
+    .join("");
+const arg = (value) => {
+    if (typeof value === "string")
+        return quote(value);
+    const command = `$(${assignments(value.env)}${shell(value.argv)})`;
+    return value.words === "one" ? `"${command}"` : command;
+};
+const describeProbe = (probe) => probe.kind === "on-path" ? `command -v ${quote(probe.program)}` : assignments(probe.env) + shell(probe.argv);
+const describe = (step) => {
+    switch (step.kind) {
+        case "run":
+            return `run      ${assignments(step.env)}${step.argv.map(arg).join(" ")}${step.stdout === "discard" ? " >/dev/null" : ""}`;
+        case "check":
+            return `${step.onFailure === "stop" ? "guard   " : "check   "} ${step.label}: ${describeProbe(step.probe)}`;
+        case "confirm":
+            return `confirm  ${step.prompt}(${step.expect})`;
+        case "note":
+            return `note     ${step.text}`;
+    }
+};
+export const render = (plan) => plan.map(describe);

package/cli/dist/result.js

@@ -0,0 +1,5 @@
+export const ok = (value) => ({ ok: true, value });
+export const err = (error) => ({ ok: false, error });
+export const map = (result, f) => result.ok ? ok(f(result.value)) : result;
+export const flatMap = (result, f) => (result.ok ? f(result.value) : result);
+export const all = (results) => results.reduce((acc, result) => flatMap(acc, (values) => map(result, (value) => [...values, value])), ok([]));

package/cloud-init.yml.tpl

@@ -0,0 +1,14 @@
+#cloud-config
+# Only what Ansible needs to get in. Everything else (packages, Docker, swap,
+# SSH hardening) is the common and docker roles' job: they run on every
+# deploy, while this runs once on first boot and can never be re-applied.
+
+hostname: ${hostname}
+
+users:
+  - name: deploy
+    groups: sudo
+    shell: /bin/bash
+    sudo: ALL=(ALL) NOPASSWD:ALL
+    ssh_authorized_keys:
+      - ${ssh_pubkey}

package/compose/authelia/configuration.yml

@@ -0,0 +1,138 @@
+# =============================================================================
+# Authelia — login for the platform's own pages (Jenkins, Traefik's
+# dashboard). Apps bring their own login; their users never live here.
+#
+# Authelia does NOT expand ${VAR} the way docker compose does. Interpolation here
+# comes from the `template` config filter (X_AUTHELIA_CONFIG_FILTERS=template),
+# which is Go templating: {{ env "DOMAIN" }}.
+#
+# Secrets are never in this file — they arrive as AUTHELIA_*_FILE env vars.
+# =============================================================================
+
+theme: 'auto'
+
+server:
+  address: 'tcp://0.0.0.0:9091/'
+
+log:
+  level: 'info'
+  format: 'text'
+
+# Passkeys are the point of this setup; TOTP and Duo would only be extra
+# surface to configure and explain.
+totp:
+  disable: true
+duo_api:
+  disable: true
+
+webauthn:
+  disable: false
+  enable_passkey_login: true
+  # A passkey assertion carrying the user-verification flag satisfies the
+  # two_factor policy on its own, so login is one Touch ID prompt rather than
+  # password-then-passkey. A stolen bootstrap password alone reaches nothing.
+  experimental_enable_passkey_uv_two_factors: true
+  display_name: '{{ env "DOMAIN" }}'
+  attestation_conveyance_preference: 'indirect'
+  timeout: '60 seconds'
+  selection_criteria:
+    attachment: ''
+    discoverability: 'required'
+    # 'required', not the default 'preferred': with 'preferred' an authenticator
+    # may omit the user-verification flag, and the user is then stuck unable to
+    # satisfy a two_factor policy.
+    user_verification: 'required'
+
+identity_validation:
+  elevated_session:
+    code_lifespan: '5 minutes'
+    elevation_lifespan: '10 minutes'
+    characters: 8
+    require_second_factor: false
+    # Once someone has one passkey, registering a second skips the one-time
+    # code entirely.
+    skip_second_factor: true
+
+authentication_backend:
+  refresh_interval: 'always'
+  # Both disabled so Authelia never writes back to users_database.yml. That
+  # file is rendered from vault on every platform run and would otherwise be
+  # silently reverted.
+  password_reset:
+    disable: true
+  password_change:
+    disable: true
+  file:
+    path: '/config/users_database.yml'
+    watch: true
+    search:
+      email: true
+      case_insensitive: true
+    password:
+      algorithm: 'argon2'
+      argon2:
+        variant: 'argon2id'
+        iterations: 3
+        # KiB, allocated per concurrent hash. The default 64 MiB is too fat for
+        # a 4 GB box with no headroom; 32 MiB is still strong for a credential
+        # used once per person, at enrolment.
+        memory: 32768
+        parallelism: 2
+        key_length: 32
+        salt_length: 16
+
+# AUTH_POLICY is always set by the platform role (default two_factor); test
+# lowers it to one_factor so staging does not need passkey enrolment.
+access_control:
+  default_policy: 'deny'
+  rules:
+    - domain: 'jenkins.{{ env "DOMAIN" }}'
+      policy: '{{ env "AUTH_POLICY" }}'
+      subject:
+        - 'group:admin'
+    - domain: 'traefik.{{ env "DOMAIN" }}'
+      policy: '{{ env "AUTH_POLICY" }}'
+      subject:
+        - 'group:admin'
+
+session:
+  name: 'authelia_session'
+  same_site: 'lax'
+  # A working day of idle time. Shorter is tempting, but a session that dies
+  # mid-form turns the next POST into a 302 to the portal and the body is lost.
+  inactivity: '8 hours'
+  expiration: '1 day'
+  remember_me: '1 week'
+  cookies:
+      # The apex, not auth.<DOMAIN> — the cookie has to reach jenkins.<DOMAIN>
+      # and traefik.<DOMAIN> too. Authelia requires this to be a suffix of (or equal to) authelia_url.
+    - domain: '{{ env "DOMAIN" }}'
+      authelia_url: 'https://auth.{{ env "DOMAIN" }}'
+
+regulation:
+  max_retries: 3
+  find_time: '2 minutes'
+  ban_time: '5 minutes'
+
+storage:
+  local:
+    path: '/data/db.sqlite3'
+
+# SMTP when it is configured, otherwise write to a file. The notifier is only
+# used for the one-time code at passkey enrolment, so the file fallback keeps
+# dev working without an external dependency.
+notifier:
+  disable_startup_check: false
+{{- if env "SMTP_ADDRESS" }}
+  smtp:
+    address: '{{ env "SMTP_ADDRESS" }}'
+    username: '{{ env "SMTP_USERNAME" }}'
+    sender: '{{ env "SMTP_SENDER" }}'
+    # In the template rather than an env var on purpose: an empty
+    # AUTHELIA_NOTIFIER_SMTP_PASSWORD still creates notifier.smtp, and Authelia
+    # then refuses to start with both notifiers configured.
+    password: {{ secret "/config/secrets/smtp_password" | msquote }}
+{{- else }}
+  filesystem:
+    filename: '/data/notification.txt'
+{{- end }}

package/compose/buildkit/buildkitd.toml

@@ -0,0 +1,14 @@
+# BuildKit daemon config.
+#
+# The registry is plain HTTP on the internal docker network and has no TLS
+# anywhere. BuildKit has to be told that explicitly or it tries HTTPS.
+
+[worker.oci]
+  enabled = true
+  # Rootless: no process sandbox, and the rootless worker cannot use overlayfs
+  # on every kernel, so let BuildKit pick a snapshotter it can actually run.
+  max-parallelism = 2
+
+[registry."registry:5000"]
+  http = true
+  insecure = true

package/compose/docker-compose.acme-dns.yml

@@ -0,0 +1,12 @@
+# =============================================================================
+# Overlay for a server whose certificates come by DNS-01 (acme_dns in its
+# vars.yml): lego, inside Traefik, reads the zone's token from a file. Added to
+# COMPOSE_FILE only there, so other servers' Traefik stays as it is.
+# =============================================================================
+
+services:
+  traefik:
+    environment:
+      HETZNER_API_TOKEN_FILE: /run/secrets/acme-dns-token
+    volumes:
+      - ./traefik/secrets:/run/secrets:ro

package/compose/docker-compose.ci.yml

@@ -0,0 +1,156 @@
+# =============================================================================
+# Platform CI overlay — Docker Registry + Jenkins (controller + agent)
+# App-agnostic: provides CI/CD infrastructure for any application.
+# Usage: docker compose -f docker-compose.yml -f docker-compose.ci.yml up
+# =============================================================================
+
+services:
+  registry:
+    image: registry:2.8.3
+    restart: unless-stopped
+    environment:
+      # registry-gc.sh deletes manifests nothing references any more.
+      - REGISTRY_STORAGE_DELETE_ENABLED=true
+    # No Traefik router: builds push to registry:5000 and the host daemon pulls
+    # from localhost:5000, so nothing outside the server needs it.
+    ports:
+      - "127.0.0.1:5000:5000"
+    volumes:
+      - registry-data:/var/lib/registry
+    networks:
+      - internal
+
+  # ---------------------------------------------------------------------------
+  # BuildKit — builds images without anyone holding the host's docker socket.
+  #
+  # The build agent used to mount /var/run/docker.sock read-write while running
+  # pipeline code checked out from arbitrary branches, which is host root by
+  # design rather than by exploit. Builds now go here instead: rootless, its own
+  # daemon, pushing straight to the registry. Compromising it gets you a
+  # container, not the box.
+  # ---------------------------------------------------------------------------
+  buildkitd:
+    image: moby/buildkit:v0.34.0-rootless
+    restart: unless-stopped
+    # Flags go in the command: this image does not read BUILDKITD_FLAGS (that
+    # is a buildx convention), and without them it listens on a unix socket
+    # the agent cannot reach.
+    command:
+      - --oci-worker-no-process-sandbox
+      - --addr
+      - tcp://0.0.0.0:1234
+    # rootlesskit needs an unprivileged user namespace, which Ubuntu 23.10+
+    # denies to unconfined processes. The named profile (installed by the docker
+    # role) grants userns to this container alone, so the host keeps the
+    # restriction.
+    security_opt:
+      - seccomp=unconfined
+      - apparmor=buildkit-rootless
+    volumes:
+      - buildkit-cache:/home/user/.local/share/buildkit
+      - ./buildkit/buildkitd.toml:/home/user/.config/buildkit/buildkitd.toml:ro
+    mem_limit: 1g
+    networks:
+      - internal
+
+  jenkins-controller:
+    build:
+      context: ./jenkins
+      dockerfile: Dockerfile
+    # The controller runs as jenkins (uid/gid 1000) and reaches the socket via
+    # the host's docker group, whose GID differs per host.
+    group_add:
+      - ${DOCKER_GID:?}
+    restart: unless-stopped
+    # No COMPOSE_PROJECT_NAME here on purpose: every app's deploy runs
+    # `docker compose` from this container, and an exported project name would
+    # beat the one the deploy passes. APPS_DIR is where app .env files live.
+    environment:
+      - JENKINS_ADMIN_USER=${JENKINS_ADMIN_USER:-admin}
+      - JENKINS_ADMIN_PASSWORD=${JENKINS_ADMIN_PASSWORD:-admin}
+      - JENKINS_GIT_REPO=${GIT_REMOTE_URL:?}
+      - GITHUB_WEBHOOK_SECRET=${GITHUB_WEBHOOK_SECRET:-}
+      - DOMAIN=${DOMAIN:-localhost}
+      - APPS_DIR=${APPS_DIR:?}
+      - PLATFORM_REF=${PLATFORM_REF:?}
+      - PLATFORM_RENOVATE=${PLATFORM_RENOVATE:-false}
+      - RENOVATE_SCHEDULE=${RENOVATE_SCHEDULE:-H 4 * * 1}
+      - RENOVATE_PLATFORM=${RENOVATE_PLATFORM:-github}
+      - RENOVATE_ENDPOINT=${RENOVATE_ENDPOINT:-}
+      - RENOVATE_GIT_URL=${RENOVATE_GIT_URL:-}
+      - RENOVATE_GITHUB_COM_TOKEN=${RENOVATE_GITHUB_COM_TOKEN:-}
+      - RENOVATE_HOST_RULES=${RENOVATE_HOST_RULES:-}
+      - RENOVATE_REPOSITORIES=${RENOVATE_REPOSITORIES:-}
+      # Tell JCasC to merge every YAML in this directory at startup.
+      - CASC_JENKINS_CONFIG=/var/jenkins_home/casc
+    volumes:
+      - jenkins-home:/var/jenkins_home
+      # The controller is the only node with the docker socket, and it runs
+      # the deploy stage, so it needs the app's compose directory too.
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ${APPS_DIR:?}:${APPS_DIR:?}:ro
+      - ./jenkins/casc:/var/jenkins_home/casc:ro
+      # One directory per app, one file per secret; JCasC reads them with
+      # ${readFile:...}. Written by bin/jenkins-app-apply.
+      - ./jenkins-secrets:/run/app-secrets:ro
+      # GIT_TOKEN and RENOVATE_TOKEN, likewise: files, so a new one needs a
+      # reload, not a restart. Written by the platform role (or forgejo-config).
+      - ./platform-secrets:/run/platform-secrets:ro
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=platform-internal"
+      - "traefik.http.routers.jenkins.rule=Host(`jenkins.${DOMAIN:-localhost}`)"
+      - "traefik.http.routers.jenkins.entrypoints=websecure"
+      - "traefik.http.routers.jenkins.tls.certresolver=le"
+      - "traefik.http.routers.jenkins.middlewares=authelia@file"
+      - "traefik.http.routers.jenkins.service=jenkins"
+      # GitHub cannot log in; the plugin checks the payload's HMAC instead.
+      - "traefik.http.routers.jenkins-webhook.rule=Host(`jenkins.${DOMAIN:-localhost}`) && Path(`/github-webhook/`)"
+      - "traefik.http.routers.jenkins-webhook.entrypoints=websecure"
+      - "traefik.http.routers.jenkins-webhook.tls.certresolver=le"
+      - "traefik.http.routers.jenkins-webhook.priority=100"
+      - "traefik.http.routers.jenkins-webhook.service=jenkins"
+      - "traefik.http.services.jenkins.loadbalancer.server.port=8080"
+    networks:
+      - internal
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://127.0.0.1:8080/login"]
+      interval: 15s
+      timeout: 5s
+      retries: 10
+      start_period: 60s
+
+  jenkins-agent:
+    build:
+      context: ./jenkins-agent
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    # Written by the platform role once Jenkins is up; absent on first start,
+    # when the agent crash-loops until the role recreates it with the secret.
+    env_file:
+      - path: ./jenkins-agent.env
+        required: false
+    environment:
+      - JENKINS_URL=http://jenkins-controller:8080
+      - JENKINS_AGENT_NAME=builder
+      - JENKINS_AGENT_WORKDIR=/home/jenkins/agent
+      - DOMAIN=${DOMAIN:-localhost}
+      # Builds go to buildkitd, not to a docker daemon. This agent runs pipeline
+      # code from untrusted branches and deliberately has no docker socket.
+      - BUILDKIT_HOST=tcp://buildkitd:1234
+      - REGISTRY_PUSH_HOST=registry:5000
+    volumes:
+      - jenkins-agent-workdir:/home/jenkins/agent
+    networks:
+      - internal
+    depends_on:
+      jenkins-controller:
+        condition: service_healthy
+      buildkitd:
+        condition: service_started
+
+volumes:
+  registry-data:
+  buildkit-cache:
+  jenkins-home:
+  jenkins-agent-workdir: