@yunuseon/kayra 0.0.0-stage → 0.4.0

package/compose/jenkins/plugins.txt

@@ -0,0 +1,97 @@
+# Every plugin, dependencies included, at the version prod runs: without the
+# dependencies pinned, jenkins-plugin-cli resolves them to whatever is newest
+# on the day the image is built. Renovate proposes updates.
+antisamy-markup-formatter:173.v680e3a_b_69ff3
+apache-httpcomponents-client-4-api:4.5.14-269.vfa_2321039a_83
+apache-httpcomponents-client-5-api:5.6.4-207.vd5b_a_c15e4de5
+asm-api:9.10.1-216.va_9256d3b_844b_
+authentication-tokens:1.144.v5ff4a_5ec5c33
+bootstrap5-api:5.3.8-1048.va_c299057e35c
+bouncycastle-api:2.30.1.86.1-306.vfc711fa_36d5f
+branch-api:2.1303.v9f3b_95dc329d
+caffeine-api:3.3.0-210.v71b_2985ce530
+checks-api:422.vc7e8b_51488c6
+cloud-stats:423.v63f017a_f582c
+cloudbees-folder:6.1106.v3a_d9a_6d2465e
+commons-compress-api:1.28.0-95.vb_e5e24f83645
+commons-lang3-api:3.21.0-122.v6a_ea_4fd34049
+commons-text-api:1.15.0-218.va_61573470393
+configuration-as-code:2133.ve570217cdb_cd
+credentials-binding:728.v902a_273b_8947
+credentials:1511.v2e3cb_0008ef0
+display-url-api:2.217.va_6b_de84cc74b_
+docker-commons:477.v289085a_b_6896
+docker-java-api:3.7.1-136.v5d70f77a_c3d6
+docker-plugin:1331.v2c036a_dc63fc
+docker-workflow:653.v2f2c08eff0ec
+durable-task:686.v80ff80875b_82
+echarts-api:6.1.0-1321.v86c4c5114494
+eddsa-api:0.3.0.1-29.v67e9a_1c969b_b_
+font-awesome-api:7.3.1-1013.v0835a_879ec6d
+git-client:6.6.1
+git:5.10.1
+github-api:1.330-492.v3941a_032db_2a_
+github:1.47.0
+gson-api:2.14.0-201.v8eefe5515533
+instance-identity:203.v15e81a_1b_7a_38
+ionicons-api:94.vcc3065403257
+jackson-annotations2-api:2.22-19.v10a_a_582ea_26e
+jackson2-api:2.22.3-447.v6a_93ce7d2c82
+jackson3-api:3.2.3-101.v69fc84453a_8e
+jakarta-activation-api:2.1.4-1
+jakarta-mail-api:2.1.5-1
+jakarta-xml-bind-api:4.0.9-19.v2b_a_5b_44d9a_1c
+javax-activation-api:1.2.0-8
+jaxb:2.3.9-143.v5979df3304e6
+job-dsl:3732.v9a_c49a_61a_313
+joda-time-api:2.15.0-208.v6b_084e7a_d9f0
+jquery3-api:3.7.1-687.v68d468e40b_30
+json-api:20260814-226.v20f9685d642c
+json-path-api:3.0.0-218.vcd4dd1355de2
+junit:1434.vde2d24df0c4c
+mailer:534.v1b_36f5864073
+matrix-project:928.v1effc3f3a_236
+mina-sshd-api-common:2.19.0-192.v2b_a_7b_2c1dc71
+mina-sshd-api-core:2.19.0-192.v2b_a_7b_2c1dc71
+okhttp-api:5.3.2-200.vedb_720a_cf1f8
+pipeline-build-step:601.v6d4c6d1a_9dc7
+pipeline-graph-analysis:254.v0f63a_a_447dca_
+pipeline-graph-view:1053.v9df19e6ceed2
+pipeline-groovy-lib:806.v408277b_33d1d
+pipeline-input-step:560.v56198a_642157
+pipeline-milestone-step:152.v6e22b_8cfc66c
+pipeline-model-api:2.2293.v6e7193cec599
+pipeline-model-definition:2.2293.v6e7193cec599
+pipeline-model-extensions:2.2293.v6e7193cec599
+pipeline-rest-api:2.41
+pipeline-stage-step:345.va_96187909426
+pipeline-stage-tags-metadata:2.2293.v6e7193cec599
+pipeline-stage-view:2.41
+pipeline-utility-steps:3.810.va_7672d206740
+plain-credentials:199.v9f8e1f741799
+plugin-util-api:7.1341.v039f146993d9
+prism-api:1.30.0-741.v034eb_0b_0a_a_fa_
+resource-disposer:0.25
+scm-api:728.vc30dcf7a_0df5
+script-security:1433.v17c58a_e45cc1
+snakeyaml-api:2.7-152.vc672728cf536
+snakeyaml-engine-api:3.2-18.v885ed7ff698f
+ssh-credentials:372.va_250881b_08cd
+ssh-slaves:3.1097.v868116049892
+structs:362.va_b_695ef4fdf9
+timestamper:1.30
+token-macro:477.vd4f0dc3cb_cf1
+trilead-api:2.284.v1974ea_324382
+variant:70.va_d9f17f859e0
+woodstox-core-api:7.3.0-16.v017f30ed004c
+workflow-aggregator:608.v67378e9d3db_1
+workflow-api:1413.v2ff1a_5e720fa_
+workflow-basic-steps:1098.v808b_fd7f8cf4
+workflow-cps:4391.v652b_b_b_1b_7c00
+workflow-durable-task-step:1479.v56e587f413a_7
+workflow-job:1609.v8926e7962024
+workflow-multibranch:842.v3a_b_59b_57b_e6e
+workflow-scm-step:487.v41313a_96b_65d
+workflow-step-api:724.v538c2362b_dfb_
+workflow-support:1015.v785e5a_b_b_8b_22
+ws-cleanup:0.49

package/compose/jenkins-agent/Dockerfile

@@ -0,0 +1,24 @@
+# =============================================================================
+# Jenkins Inbound Agent — git + buildctl + jq, nothing app-specific.
+#
+# Deliberately has NO docker CLI and no docker socket: it runs code from
+# arbitrary branches, and the host's socket would make that host root. Images
+# are built by buildkitd over TCP. No language toolchain either: apps build and
+# test inside their Dockerfiles, so a new app never changes this image.
+# =============================================================================
+
+FROM jenkins/inbound-agent:3386.v353e57a_1b_ea_0-1-jdk21
+
+USER root
+
+# renovate: datasource=github-releases depName=moby/buildkit
+ARG BUILDKIT_VERSION=v0.34.0
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates curl jq && \
+    arch="$(dpkg --print-architecture)" && \
+    curl -fsSL "https://github.com/moby/buildkit/releases/download/${BUILDKIT_VERSION}/buildkit-${BUILDKIT_VERSION}.linux-${arch}.tar.gz" \
+      | tar -xz -C /usr/local bin/buildctl && \
+    rm -rf /var/lib/apt/lists/*
+
+USER jenkins

package/compose/traefik/dynamic/authelia.yml

@@ -0,0 +1,18 @@
+# Dynamic Traefik configuration — Authelia forward authentication.
+# Referenced from router labels as `authelia@file`.
+http:
+  middlewares:
+    authelia:
+      forwardAuth:
+        address: 'http://authelia:9091/api/authz/forward-auth'
+        # Safe because neither entrypoint in traefik.yml sets
+        # forwardedHeaders.trustedIPs, so Traefik overwrites any client-supplied
+        # X-Forwarded-* before this middleware runs. Do not add trustedIPs.
+        trustForwardHeader: true
+        # The regex form strips every matching header from the inbound request
+        # before copying Authelia's back, closing the gap where Authelia
+        # returns no value for one of them and a client-supplied one survives.
+        authResponseHeadersRegex: '^Remote-(User|Groups|Email|Name)$'
+        # Traefik warns on every request without this. Authelia's auth
+        # responses are small; an unbounded body is a memory-exhaustion vector.
+        maxResponseBodySize: 8192

package/compose/traefik/dynamic/middlewares.yml

@@ -0,0 +1,14 @@
+# Dynamic Traefik configuration — middlewares
+http:
+  middlewares:
+    # Security headers for all services
+    security-headers:
+      headers:
+        browserXssFilter: true
+        contentTypeNosniff: true
+        frameDeny: true
+        sslRedirect: false
+        customFrameOptionsValue: "SAMEORIGIN"
+        stsSeconds: 31536000
+        stsIncludeSubdomains: true
+        referrerPolicy: "strict-origin-when-cross-origin"

package/compose/traefik/dynamic/ratelimit.yml

@@ -0,0 +1,21 @@
+# Dynamic Traefik configuration — rate limiting.
+http:
+  middlewares:
+    # The trial-request endpoint is public and unauthenticated by design: it is
+    # how strangers reach the club. That also makes it the one spam vector in
+    # the system, so it gets a ceiling.
+    #
+    # No sourceCriterion: the default keys on the client's remote address,
+    # which is correct when Traefik is the edge. An ipStrategy.depth here would
+    # expect an X-Forwarded-For chain that does not exist for a direct client,
+    # and the limit silently never engages.
+    #
+    # Values are empirical, not arithmetic: shorter periods did not actually
+    # throttle in testing, this regime does. 20 per 10 minutes with a burst of
+    # 5 is far more than a human filling in a form once, and caps a spammer at
+    # roughly 3k/day.
+    trial-ratelimit:
+      rateLimit:
+        average: 20
+        period: "10m"
+        burst: 5

package/compose/traefik/dynamic/tls.yml

@@ -0,0 +1,9 @@
+# Dynamic TLS — file-based certificates for local + VM development.
+# Generated by `make certs [VM_DOMAIN=...]` (mkcert under the hood).
+# In prod, this directory is empty and ACME (Let's Encrypt) handles certs
+# automatically. Traefik logs a warning for missing files but routes still
+# work via the entrypoint's default certResolver.
+tls:
+  certificates:
+    - certFile: /certs/cert.pem
+      keyFile: /certs/key.pem

package/compose/traefik/traefik.yml

@@ -0,0 +1,46 @@
+# Traefik static configuration
+api:
+  dashboard: true
+  # No insecure listener: the dashboard is served through a normal router on
+  # traefik.<DOMAIN>, behind Authelia. See docker-compose.yml.
+  insecure: false
+
+entryPoints:
+  web:
+    address: ":80"
+    http:
+      redirections:
+        entryPoint:
+          to: websecure
+          scheme: https
+          permanent: true
+  websecure:
+    address: ":443"
+    http:
+      tls:
+        certResolver: le
+      # Every router, apps included: HSTS on half the hosts protects nothing.
+      middlewares:
+        - security-headers@file
+
+certificatesResolvers:
+  le:
+    acme:
+      # Traefik does not expand env vars in its static file; the platform role
+      # substitutes acme_email on copy. Local dev never registers.
+      email: "acme@example.com"
+      storage: /acme/acme.json
+      httpChallenge:
+        entryPoint: web
+
+providers:
+  docker:
+    endpoint: "unix:///var/run/docker.sock"
+    exposedByDefault: false
+    network: platform-public
+  file:
+    directory: /etc/traefik/dynamic
+    watch: true
+
+log:
+  level: INFO

package/hosts.conf

@@ -0,0 +1,6 @@
+# Platform subdomains to add to /etc/hosts and to the mkcert SAN list.
+# App subdomains live in each app's app.yml; apps may not claim these.
+# One subdomain per line. Read by infrastructure/scripts/local/setup-hosts.sh and infrastructure/scripts/local/certs.sh.
+jenkins
+auth
+traefik

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@yunuseon/kayra",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "A self-hosted app platform and the CLI that runs it: Traefik, Authelia, Jenkins, a registry and rootless BuildKit per server, set up with OpenTofu and Ansible.",
+  "license": "MIT",
+  "author": "Yunus Öztürk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yunuseon/kayra.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "kayra": "bin/kayra.js"
+  },
+  "files": [
+    "bin/",
+    "cli/dist/",
+    "ansible/",
+    "compose/",
+    "terraform/",
+    "scripts/",
+    "cloud-init.yml.tpl",
+    "hosts.conf"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "kayra": "node cli/src/main.ts",
+    "build": "tsc -p cli/tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p cli --noEmit",
+    "lint": "cd cli && eslint --flag unstable_native_nodejs_ts_config .",
+    "test": "node --test 'cli/test/**/*.test.ts'"
+  },
+  "dependencies": {
+    "@optique/core": "1.3.3",
+    "@optique/run": "1.3.3",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@tsconfig/node24": "24.0.5",
+    "@tsconfig/strictest": "2.0.8",
+    "@types/node": "24.19.1",
+    "eslint": "10.12.0",
+    "eslint-plugin-functional": "10.0.1",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.71.1"
+  },
+  "overrides": {
+    "eslint-plugin-functional": {
+      "deepmerge-ts": "8.0.2"
+    }
+  },
+  "homepage": "https://github.com/yunuseon/kayra#readme",
+  "bugs": {
+    "url": "https://github.com/yunuseon/kayra/issues"
+  },
+  "keywords": [
+    "paas",
+    "self-hosted",
+    "platform",
+    "traefik",
+    "jenkins",
+    "ansible",
+    "opentofu",
+    "hetzner",
+    "docker-compose"
+  ]
+}

package/scripts/local/app-manifests.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Print the path of every app.yml a server runs, one per line, from the
+# platform's cache of each app's repo (.cache/apps/<name>, the same clone the
+# app role reads). A missing clone is
+# fetched with the operator's own git credentials (kayra doctor checks them).
+#
+# Usage: FLEET_ROOT=<fleet> bash scripts/local/app-manifests.sh [--subdomains] <server-name>
+#   --subdomains  print the apps' subdomains instead (for certs and /etc/hosts)
+set -euo pipefail
+
+FLEET_ROOT="${FLEET_ROOT:?the directory of the fleet (servers/), set by kayra}"
+subdomains=false
+[ "${1:-}" != "--subdomains" ] || { subdomains=true; shift; }
+name="${1:?Usage: app-manifests.sh [--subdomains] <server-name>}"
+descriptor="${FLEET_ROOT}/servers/${name}/server.yml"
+
+yq -o json -I0 '.apps // [] | .[]' "$descriptor" | while read -r app; do
+  path="$(jq -r '.path // "."' <<< "$app")"
+  repo="$(jq -r '.repo' <<< "$app")"
+  clone="${FLEET_ROOT}/.cache/apps/$(jq -r '.name' <<< "$app")"
+  if [ ! -d "${clone}/.git" ]; then
+    git clone -q --depth 1 --branch "$(jq -r '.ref // "main"' <<< "$app")" "$repo" "$clone"
+  fi
+  manifest="${clone}/${path}/app.yml"
+  if [ "$subdomains" = true ]; then yq '.subdomains[]' "$manifest"; else echo "$manifest"; fi
+done

package/scripts/local/authelia-dev-init.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Generate local Authelia secrets and a dev user database.
+#
+# Mirrors scripts/local/certs.sh: local-only material, generated on demand and
+# gitignored, never committed. Production gets both from Ansible + vault.
+#
+# Usage: bash scripts/local/authelia-dev-init.sh <authelia-dir> <dev-email> <dev-password>
+set -euo pipefail
+
+usage="Usage: authelia-dev-init.sh <authelia-dir> <dev-email> <dev-password>"
+AUTHELIA_DIR="${1:?$usage}"
+DEV_EMAIL="${2:?$usage}"
+DEV_PASSWORD="${3:?$usage}"
+IMAGE="authelia/authelia:4.39.28"
+
+SECRETS_DIR="${AUTHELIA_DIR}/secrets"
+USERS_FILE="${AUTHELIA_DIR}/users_database.yml"
+
+mkdir -p "${SECRETS_DIR}"
+
+for name in session storage_encryption; do
+  target="${SECRETS_DIR}/${name}"
+  if [ ! -s "${target}" ]; then
+    echo "==> Generating ${name}..."
+    openssl rand -hex 32 > "${target}"
+    chmod 600 "${target}"
+  fi
+done
+
+if [ -s "${USERS_FILE}" ]; then
+  echo "==> ${USERS_FILE} exists — leaving it alone."
+  exit 0
+fi
+
+echo "==> Hashing the dev password (argon2id)..."
+# Authelia's own hasher, so parameters always match configuration.yml.
+  # --memory is KiB here, matching the config's `memory:` key exactly.
+HASH="$(docker run --rm "${IMAGE}" \
+  authelia crypto hash generate argon2 \
+    --variant argon2id --iterations 3 --memory 32768 --parallelism 2 \
+    --password "${DEV_PASSWORD}" \
+  | sed 's/^Digest: //')"
+
+cat > "${USERS_FILE}" <<YML
+# Local development only — generated by scripts/local/authelia-dev-init.sh.
+# Production renders this from vault; see the platform Ansible role.
+users:
+  dev:
+    disabled: false
+    displayname: 'Dev'
+    password: '${HASH}'
+    email: '${DEV_EMAIL}'
+    groups: ['admin']
+YML
+chmod 600 "${USERS_FILE}"
+
+echo ""
+echo "Done — dev login: ${DEV_EMAIL} / ${DEV_PASSWORD}"

package/scripts/local/certs.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Generate local-trusted TLS certs (mkcert) for Traefik.
+# Covers `<domain>`, `*.<domain>`, the platform's subdomains and the given ones.
+#
+# Usage: bash scripts/local/certs.sh <domain> <certs-dir> [subdomain…]
+# Output: <certs-dir>/cert.pem, <certs-dir>/key.pem
+#
+# A no-op when the existing cert already covers <domain>. Local dev and the
+# multipass VM share one certs dir with different domains, so "the file exists"
+# is not enough: shipping the local cert to the VM would break every hostname.
+set -euo pipefail
+
+KAYRA_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+DOMAIN="${1:?Usage: certs.sh <domain> <certs-dir> [subdomain…]}"
+CERTS_DIR="${2:?}"
+shift 2
+
+if [ -f "${CERTS_DIR}/key.pem" ] && [ -f "${CERTS_DIR}/cert.pem" ] \
+   && openssl x509 -in "${CERTS_DIR}/cert.pem" -noout -ext subjectAltName | grep -qE "DNS:${DOMAIN}(,|$)"; then
+  exit 0
+fi
+
+if ! command -v mkcert >/dev/null 2>&1; then
+  echo "ERROR: mkcert not installed. Run: brew install mkcert nss && mkcert -install" >&2
+  exit 1
+fi
+
+# First run on this machine? Install the local CA into the system trust store.
+if [ ! -f "$(mkcert -CAROOT)/rootCA.pem" ]; then
+  echo "==> Installing mkcert local CA (one-time, may prompt for sudo)..."
+  mkcert -install
+fi
+
+mkdir -p "${CERTS_DIR}"
+
+# Explicit subdomain SANs alongside the wildcard: Apple's SecureTransport (used
+# by macOS-bundled curl) doesn't match `*.domain` wildcards. Chrome is fine, but
+# pipelines and smoke tests that use system curl break without these.
+NAMES=("${DOMAIN}" "*.${DOMAIN}")
+for sub in $(awk '!/^[[:space:]]*(#|$)/ {print $1}' "${KAYRA_ROOT}"/hosts.conf) "$@"; do
+  NAMES+=("${sub}.${DOMAIN}")
+done
+# Keep plain localhost working for native (non-compose) dev.
+NAMES+=(localhost "*.localhost" 127.0.0.1 ::1)
+
+echo "==> Generating cert for ${DOMAIN} (${#NAMES[@]} names)..."
+mkcert \
+  -cert-file "${CERTS_DIR}/cert.pem" \
+  -key-file  "${CERTS_DIR}/key.pem" \
+  "${NAMES[@]}"
+
+chmod 644 "${CERTS_DIR}/cert.pem"
+chmod 600 "${CERTS_DIR}/key.pem"
+
+echo "Done — ${CERTS_DIR}/cert.pem + key.pem"

package/scripts/local/home-image.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Builds what a target: home server boots from, since nothing can create it
+# for us: the Ubuntu cloud image, grown to vm.disk, and a seed ISO with the
+# same cloud-init as every other server plus its fixed address. Both go into
+# the hypervisor by hand, once: the image as the VM's disk, the ISO as a CD.
+#
+# Usage: FLEET_ROOT=<fleet> bash scripts/local/home-image.sh <server-name>
+# Writes servers/<name>/vm/ (gitignored): <name>.qcow2, seed.iso.
+set -euo pipefail
+
+FLEET_ROOT="${FLEET_ROOT:?the directory of the fleet (servers/), set by kayra}"
+KAYRA_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+name="${1:?Usage: home-image.sh <server-name>}"
+dir="${FLEET_ROOT}/servers/${name}"
+out="${dir}/vm"
+
+# Pinned. Only the first boot uses it; Ansible keeps the server current after.
+image_url=https://cloud-images.ubuntu.com/releases/noble/release-20260926/ubuntu-24.04-server-cloudimg-amd64.img
+image_sha256=6a81c37564db9b1ee84e141922625e1d7c5b389b99bb3c572e0243607d5bb4d2
+
+command -v qemu-img >/dev/null || { echo "ERROR: qemu-img not installed. Run: brew install qemu" >&2; exit 1; }
+
+address="$(yq '.vm.address' "${dir}/vars.yml")"
+gateway="$(yq '.vm.gateway' "${dir}/vars.yml")"
+disk="$(yq '.vm.disk' "${dir}/vars.yml")"
+key="$(sed -n 's/.*ansible_ssh_private_key_file=\([^ ]*\).*/\1/p' "${dir}/inventory.ini" | head -1).pub"
+
+mkdir -p "${out}/seed"
+image="${out}/cloudimg-${image_sha256:0:12}.img"
+if [ ! -f "$image" ]; then
+    curl -fL --progress-bar -o "${image}.part" "$image_url"
+    mv "${image}.part" "$image"
+fi
+echo "${image_sha256}  ${image}" | shasum -a 256 -c --quiet
+
+rm -f "${out}/${name}.qcow2"
+qemu-img convert -O qcow2 "$image" "${out}/${name}.qcow2"
+qemu-img resize -q "${out}/${name}.qcow2" "$disk"
+
+sed -e "s|[$]{hostname}|${name}|" -e "s|[$]{ssh_pubkey}|$(cat "$key")|" \
+    "${KAYRA_ROOT}/cloud-init.yml.tpl" > "${out}/seed/user-data"
+printf 'instance-id: %s\nlocal-hostname: %s\n' "$name" "$name" > "${out}/seed/meta-data"
+cat > "${out}/seed/network-config" <<NETWORK
+version: 2
+ethernets:
+  lan:
+    match: {name: "e*"}
+    addresses: [${address}]
+    routes: [{to: default, via: ${gateway}}]
+    nameservers: {addresses: [${gateway}]}
+NETWORK
+
+rm -f "${out}/seed.iso"
+hdiutil makehybrid -quiet -iso -joliet -default-volume-name cidata -o "${out}/seed.iso" "${out}/seed"
+echo "Built ${out}/${name}.qcow2 (${disk}) and ${out}/seed.iso: import the first as the VM's disk, attach the second as a CD."

package/scripts/local/home-reach.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Can Ansible get into a home machine (target: home)? If not, say why, in the
+# terms of the failures seen there, before Ansible's UNREACHABLE does not.
+#
+# Usage: FLEET_ROOT=<fleet> bash scripts/local/home-reach.sh <server-name> <kind>
+set -euo pipefail
+
+FLEET_ROOT="${FLEET_ROOT:?the directory of the fleet (servers/), set by kayra}"
+name="${1:?Usage: home-reach.sh <server-name> <kind>}"
+kind="${2:?Usage: home-reach.sh <server-name> <kind>}"
+inv="${FLEET_ROOT}/servers/${name}/inventory.ini"
+field() { sed -n "s/.*${1}=\([^ ]*\).*/\1/p" "$inv" | head -1; }
+host="$(field ansible_host)"
+user="$(field ansible_user)"
+key="$(field ansible_ssh_private_key_file)"
+port="$(field ansible_port)"
+
+if out="$(ssh -o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=accept-new \
+    -p "${port:-22}" -i "${key/#\~/$HOME}" "${user}@${host}" true 2>&1)"; then
+  exit 0
+fi
+
+echo "ERROR: cannot SSH into ${name} (${user}@${host}):" >&2
+echo "$out" | grep -v '^\*\*' | sed 's/^/  /' >&2
+case "$out" in
+  *"Connection refused"*)
+    if [ "$kind" = nas ]; then
+      echo "  SSH is off: it is on only on demand, for a set time. UGOS: Control Panel → Terminal → SSH on." >&2
+    else
+      echo "  Nothing listens on port ${port:-22}: is the machine up and sshd running?" >&2
+    fi ;;
+  *"Permission denied"*)
+    echo "  The key is refused. Is it in the agent? ssh-add ${key}" >&2
+    if [ "$kind" = nas ]; then
+      echo "  If it is: UGOS resets permissions, and sshd ignores a writable ~/.ssh. On the NAS:" >&2
+      echo "    chmod 755 ~ && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys" >&2
+    fi ;;
+  *"timed out"*|*"No route to host"*|*"not known"*)
+    echo "  ${host} does not answer: is the machine on, and is this Mac on the home network?" >&2 ;;
+esac
+exit 1

package/scripts/local/require-main.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Refuse to change a real server from anything but main as merged.
+#
+# Every kayra command deploys the local checkout, whatever it is. A
+# test server may track a branch (that is how platform changes are tested);
+# every other server is only ever changed from a clean main that matches
+# origin/main, so what runs there is exactly what was reviewed and merged.
+# Uncommitted changes in other servers' folders do not count: a test server's
+# branch pointers must not block a prod deploy.
+#
+# Usage: FLEET_ROOT=<fleet> bash scripts/local/require-main.sh <server-name>
+set -euo pipefail
+
+FLEET_ROOT="${FLEET_ROOT:?the directory of the fleet (servers/), set by kayra}"
+name="${1:?Usage: require-main.sh <server-name>}"
+target="$(yq '.target' "${FLEET_ROOT}/servers/${name}/server.yml")"
+[ "$target" != "multipass" ] || exit 0
+
+fail() {
+    echo "ERROR: ${name} is a ${target} server and is only changed from main as merged." >&2
+    echo "  $*" >&2
+    exit 1
+}
+
+cd "$FLEET_ROOT"
+branch="$(git branch --show-current)"
+[ "$branch" = "main" ] || fail "The checkout is on '${branch:-a detached HEAD}'. Merge it, then: git switch main && git pull"
+git fetch -q origin main || fail "Could not fetch origin/main to compare against."
+[ "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)" ] \
+    || fail "Local main differs from origin/main. Pull, and send unpushed commits through a PR."
+
+others=()
+for dir in servers/*/; do
+    [ "$dir" = "servers/${name}/" ] || others+=(":(exclude)${dir}")
+done
+dirty="$(git status --porcelain --untracked-files=no -- . "${others[@]}")"
+[ -z "$dirty" ] || fail "Uncommitted changes would be deployed; commit them through a PR first:
+${dirty}"

package/scripts/local/setup-hosts.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Point <domain> and its subdomains at <ip> in /etc/hosts. Requires sudo.
+# Subdomains: the platform's (hosts.conf) plus the given ones —
+# callers pass their apps' subdomains, as they do to certs.sh.
+#
+# Usage: bash scripts/local/setup-hosts.sh <domain> <ip> [subdomain…]
+set -euo pipefail
+
+KAYRA_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+DOMAIN="${1:?Usage: setup-hosts.sh <domain> <ip>}"
+IP="${2:?Usage: setup-hosts.sh <domain> <ip> [subdomain…]}"
+shift 2
+
+echo "==> Updating /etc/hosts for ${DOMAIN} -> ${IP}..."
+
+if grep -q "${DOMAIN}" /etc/hosts 2>/dev/null; then
+  echo "    Removing old entries..."
+  sudo sed -i.bak "/${DOMAIN}/d" /etc/hosts
+fi
+
+HOSTS=""
+for sub in $(awk '!/^[[:space:]]*(#|$)/ {print $1}' "${KAYRA_ROOT}"/hosts.conf) "$@"; do
+  HOSTS="${HOSTS} ${sub}.${DOMAIN}"
+done
+
+echo "${IP} ${DOMAIN}${HOSTS}" | sudo tee -a /etc/hosts > /dev/null
+
+echo ""
+echo "Done — /etc/hosts updated:"
+grep "${DOMAIN}" /etc/hosts

package/scripts/server/app-purge

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# =============================================================================
+# app-purge <app> — delete a removed app's Docker volumes, i.e. its data.
+#
+# Refuses while the app is still registered here: purging is the second,
+# deliberate step after `app-remove`, never a way around it.
+#
+# Installed by the platform role at <platform_dir>/bin. Run as root.
+# =============================================================================
+set -euo pipefail
+
+app="${1:?Usage: app-purge <app>}"
+platform_dir="$(cd "$(dirname "$0")/.." && pwd)"
+
+if [ -e "${platform_dir}/jenkins/casc/10-${app}.yaml" ]; then
+    echo "ERROR: ${app} is still registered on this server — remove it from server.yml and run \`kayra apps <server>\` first." >&2
+    exit 1
+fi
+volumes=$(docker volume ls -q --filter "label=com.docker.compose.project=${app}")
+if [ -z "$volumes" ]; then
+    echo "No volumes left for ${app}."
+    exit 0
+fi
+# Word-splitting on purpose: one volume name per line, none contain spaces.
+# shellcheck disable=SC2086
+docker volume rm $volumes