@yunuseon/kayra 0.5.1 → 0.7.0

package/cli/dist/schemas.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { appManifestSchema, appValuesSchema, defaultsSchema, serverKinds, serverSchema, settings, varsSchema, } from "./settings.js";
+const version = "https://json-schema.org/draft/2020-12/schema";
+const jsonSchema = (title, schema) => ({
+    ...z.toJSONSchema(schema, { target: "draft-2020-12", unrepresentable: "any" }),
+    $schema: version,
+    title,
+});
+/** The fleet's files as JSON Schemas, for editors: published in the package under schema/. */
+export const jsonSchemas = () => ({
+    "server.json": jsonSchema("server.yml", serverSchema),
+    "defaults.json": jsonSchema("defaults.yml", defaultsSchema),
+    ...Object.fromEntries(serverKinds.map((kind) => [`vars-${kind}.json`, jsonSchema(`vars.yml (kind ${kind})`, varsSchema(kind))])),
+    "app.json": jsonSchema("app.yml", appManifestSchema),
+    "app-values.json": jsonSchema("apps/<app>.yml and apps/<app>.secrets.yml", appValuesSchema),
+});
+const kindsOf = (each) => each.kinds.join(", ");
+/** MDX reads <…> as a component and {…} as an expression; a table cell's | ends it. */
+const escaped = (description) => description.replaceAll("|", "\\|").replaceAll("<", "&lt;").replaceAll("{", "&#123;").replaceAll("}", "&#125;");
+const row = (each) => `| \`${each.name}\` | ${kindsOf(each)} | ${escaped(each.description)} |`;
+const table = (chosen) => ["| Setting | Kinds | What it is |", "|---|---|---|", ...chosen.map(row)].join("\n");
+const editorLine = (kind) => `# yaml-language-server: $schema=../../node_modules/@yunuseon/kayra/schema/vars-${kind}.json`;
+/** The docs site's settings page, generated from the same registry as the schemas. */
+export const settingsPage = () => [
+    "---",
+    "title: Settings",
+    "description: Every setting a fleet can give its servers, generated from kayra's schemas.",
+    "---",
+    "",
+    "{/* Generated by `npm run schemas` from cli/src/settings.ts — edit there, not here. */}",
+    "",
+    "A server's `vars.yml` may set the settings of its kind and nothing else: an unknown key stops every",
+    "kayra command, with a suggestion where it looks like a typo. `servers/defaults.yml` holds settings",
+    "shared by every server. Secrets go in `secrets.yml` — a secret in `vars.yml` is refused.",
+    "",
+    "Editors complete and check these files from the JSON Schemas in the package (`schema/`), e.g. as",
+    "the first line of a platform server's `vars.yml`:",
+    "",
+    "```yaml",
+    editorLine("platform"),
+    "```",
+    "",
+    "## Settings",
+    "",
+    table(settings.filter((each) => !each.secret)),
+    "",
+    "## Secrets",
+    "",
+    table(settings.filter((each) => each.secret)),
+    "",
+    "Ansible's own variables (`ansible_*`) are allowed everywhere.",
+    "",
+].join("\n");

package/cli/dist/settings.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+/** The server kinds, each with its playbook; settings say which kinds read them. */
+export const serverKinds = ["platform", "edge", "nas"];
+const setting = (name, kinds, schema, description) => ({ name, kinds, secret: false, schema: schema.describe(description), description });
+const secret = (name, kinds, schema, description) => ({ name, kinds, secret: true, schema: schema.describe(description), description });
+const text = z.string();
+const texts = z.array(z.string());
+const platform = ["platform"];
+const edge = ["edge"];
+const nas = ["nas"];
+/** Nested settings check the fields they know and allow others: a typo is caught at the top. */
+const record = (fields) => z.looseObject(fields);
+export const settings = [
+    // Every kind that serves HTTPS
+    setting("acme_email", ["platform", "edge"], text, "The Let's Encrypt account contact: expiry warnings land here."),
+    setting("docker_version", ["platform", "edge"], text, "The Docker CE major the docker role pins and holds, as an apt version glob (default 5:29*)."),
+    // platform: the platform role
+    setting("git_remote_url", platform, text, "kayra's repository: Jenkins loads the pipeline library and platform jobs from it."),
+    setting("platform_ref", platform, text, "The ref of git_remote_url Jenkins loads from; defaults to the tag of the kayra version that ran (v<version>). Only a test server sets a branch."),
+    setting("jenkins_admin_user", platform, text, "Jenkins' local admin user (default admin)."),
+    setting("authelia_policy", platform, z.enum(["one_factor", "two_factor"]), "What Authelia asks of staff: two_factor (default) or one_factor."),
+    setting("authelia_smtp_address", platform, text, "SMTP server for Authelia's mails (passkey enrolment); empty: mails go to a file."),
+    setting("authelia_smtp_username", platform, text, "SMTP user for Authelia."),
+    setting("authelia_smtp_sender", platform, text, "Sender address of Authelia's mails."),
+    setting("acme_dns", platform, z.enum(["", "hetzner"]), "Certificates by DNS-01 instead of HTTP-01, for a server the internet never reaches: the DNS provider (hetzner)."),
+    setting("renovate_repositories", platform, texts, "owner/repo of the repos this server's platform-renovate keeps up to date; the job exists only where the list is not empty."),
+    setting("renovate_schedule", platform, text, "When platform-renovate runs, as a Jenkins cron spec (default weekly: H 4 * * 1)."),
+    setting("renovate_platform", platform, z.enum(["github", "forgejo"]), "Where the repos live: github (default) or forgejo."),
+    setting("renovate_endpoint", platform, text, "With a Forgejo: its API on platform-internal, e.g. http://forgejo:3000/api/v1."),
+    setting("renovate_git_url", platform, z.enum(["default", "ssh", "endpoint"]), "How Renovate clones; endpoint with a Forgejo, so it uses the internal address."),
+    setting("renovate_host_rules", platform, z.array(record({ matchHost: text })), "Renovate hostRules: allowInternal for a Forgejo on platform-internal, credentials for a private registry."),
+    setting("vm", platform, record({ address: text, gateway: text, disk: text }), "target home: the VM kayra provision builds — fixed address (CIDR), gateway, disk size."),
+    setting("forgejo_config", platform, record({
+        url: text,
+        container: text,
+        runners: z.array(record({ name: text, scope: text.optional() })).optional(),
+        tokens: z.array(record({ user: text, name: text, scopes: texts, secret: text })).optional(),
+        users: z.array(record({ name: text, email: text })).optional(),
+        orgs: z.array(record({ name: text, owner: text, visibility: z.enum(["public", "limited", "private"]) })).optional(),
+        ssh_keys: z.array(record({ user: text, title: text, key: text })).optional(),
+        repos: z
+            .array(record({
+            name: text,
+            settings: z.record(z.string(), z.unknown()).optional(),
+            collaborators: z.array(record({ user: text, permission: text })).optional(),
+            webhooks: texts.optional(),
+            push_mirror: text.optional(),
+            pull_mirror: text.optional(),
+        }))
+            .optional(),
+    }), "What this server's own Forgejo holds, as code: users, SSH keys, organizations, runners, repos (settings, collaborators, webhooks, mirrors) and the tokens it mints for the platform."),
+    // platform and nas: the compose-stacks role
+    setting("compose_stacks", ["platform", "nas"], record({ dir: text, stacks: texts }), "The server's own compose stacks: their directory on the server and the names under stacks/ to run."),
+    // nas
+    setting("nas_root", nas, text, "The only directory the NAS play writes in, asserted before any change (e.g. /volume2)."),
+    setting("restic_backup", nas, record({
+        dir: text,
+        repository: text,
+        schedule: text,
+        restore_test_schedule: text,
+        paths: texts,
+        restore_test_paths: texts.optional(),
+        exclude: texts.optional(),
+        keep: record({ daily: z.number(), weekly: z.number(), monthly: z.number() }).optional(),
+        ssh: record({ public_key: text, host: text, user: text, port: z.number(), known_host: text }).optional(),
+    }), "The nightly restic backup: what, where to (SFTP), when, how long kept, and the monthly restore test."),
+    // edge
+    setting("wireguard", edge, record({ address: text, port: z.number(), peer_public_key: text, peer_allowed_ips: texts, keepalive: z.number().optional() }), "The tunnel into the private network: the edge's address, port, and the one peer (its key, what it may reach)."),
+    setting("edge_routes", edge, z.array(record({ subdomains: texts, upstream: text, forwarded_headers: z.boolean().optional() })), "Public names the edge serves: subdomains of the domain and the upstream inside the tunnel they go to."),
+    setting("backup_check", edge, record({
+        stale_after_hours: z.number(),
+        github_repository: text,
+        github_app_id: text,
+        repositories: z.array(record({ name: text, url: text, user: text, restore_test_max_days: z.number().optional() })),
+    }), "The hourly check of the private network's backups: when a snapshot is stale, where issues go, which repositories."),
+    // Secrets
+    secret("jenkins_admin_password", platform, text, "Jenkins' admin password."),
+    secret("git_token", platform, text, "Token Jenkins clones and posts commit statuses with."),
+    secret("github_webhook_secret", platform, text, "HMAC secret of the apps' GitHub push webhooks."),
+    secret("renovate_token", platform, text, "Token platform-renovate opens PRs with."),
+    secret("renovate_github_com_token", platform, text, "Public-read GitHub token for Renovate's lookups off GitHub."),
+    secret("authelia_session_secret", platform, text, "Authelia's session secret."),
+    secret("authelia_storage_encryption_key", platform, text, "Authelia's storage encryption key."),
+    secret("authelia_smtp_password", platform, text, "Authelia's SMTP password."),
+    secret("authelia_users", platform, z.record(z.string(), z.unknown()), "Staff accounts: name, email, argon2id password hash."),
+    secret("acme_dns_token", platform, text, "With acme_dns: the DNS provider's token, for DNS-01 only."),
+    secret("forgejo_admin_token", platform, text, "forgejo-config's token: admin, organization, repository, user (read and write)."),
+    secret("forgejo_runner_secrets", platform, z.record(z.string(), text), "Per runner name: the 40-character secret shared by the runner and Forgejo."),
+    secret("forgejo_action_secrets", platform, z.array(record({ repo: text, name: text, value: text })), "Actions secrets per repo."),
+    secret("forgejo_push_mirror_credentials", platform, record({ username: text, password: text }), "The account push mirrors push with."),
+    secret("compose_stack_secrets", ["platform", "nas"], z.record(z.string(), z.record(z.string(), z.unknown())), "Per stack: the variables of its .env."),
+    secret("compose_registry_logins", ["platform", "nas"], z.array(record({ registry: text, username: text, password: text })), "Private registries the stacks pull from."),
+    secret("restic_backup_password", nas, text, "The restic repository's password."),
+    secret("restic_backup_ssh_key", nas, text, "The SSH key the backup reaches the Storage Box with."),
+    secret("restic_backup_postgres_passwords", nas, z.record(z.string(), text), "Per database container: the password its dump connects with."),
+    secret("wireguard_private_key", edge, text, "The edge's WireGuard private key."),
+    secret("wireguard_peer_psk", edge, text, "The tunnel's preshared key."),
+    secret("backup_check_github_app_key", edge, text, "The GitHub App's private key the backup check opens issues with."),
+    secret("backup_check_passwords", edge, z.record(z.string(), text), "Per watched repository: its read-only password."),
+];
+/** Ansible's own variables (connection, privilege escalation) are always allowed. */
+export const isAnsibleVariable = (key) => key.startsWith("ansible_");
+export const settingsFor = (kind, secrets) => settings.filter((each) => each.secret === secrets && each.kinds.includes(kind));
+const shape = (chosen) => Object.fromEntries(chosen.map((each) => [each.name, each.schema.optional()]));
+/** vars.yml for a kind: its settings and nothing else (Ansible's own variables apart). */
+export const varsSchema = (kind) => z.strictObject(shape(settingsFor(kind, false)));
+/** defaults.yml: settings shared by every server, so any kind's. */
+export const defaultsSchema = z.strictObject(shape(settings.filter((each) => !each.secret)));
+/** secrets.yml: the known secrets typed; other keys may be helpers that vars.yml references. */
+export const secretsSchema = (kind) => z.looseObject(shape(settingsFor(kind, true)));
+/** server.yml: topology only. */
+export const serverSchema = z.strictObject({
+    kind: z.enum(serverKinds).optional().describe("Which playbook: platform (default; Traefik, Authelia, Jenkins, apps), edge or nas."),
+    target: z.enum(["hetzner", "multipass", "home"]).describe("Where it runs: hetzner, multipass (a local VM) or home (a machine nothing creates)."),
+    domain: z.string().describe("The server's domain; platform subdomains and the apps' hang off it."),
+    vault: z.boolean().optional().describe("secrets.yml is vault-encrypted (required outside multipass)."),
+    vault_password_file: z.string().optional().describe("The vault password file; without it, Ansible asks."),
+    apps: z
+        .array(z.strictObject({
+        name: z.string(),
+        repo: z.string().describe("The app's repository, https://."),
+        ref: z.string().optional().describe("The branch to build and deploy (default main)."),
+        path: z.string().optional().describe("The app's root inside the repository (default .)."),
+    }))
+        .optional()
+        .describe("The apps this server runs (platform only)."),
+});
+/** app.yml, at the root of an app's repository: the app contract. */
+export const appManifestSchema = z.strictObject({
+    name: z.string().describe("The app's name, as in the server.yml entry."),
+    compose: z.array(z.string()).describe("Compose files, relative to the app root, in order."),
+    subdomains: z.array(z.string()).describe("Hostnames the app claims: <sub>.<domain>."),
+    secrets: z.array(z.string()).optional().describe("Secret keys; their values come from the fleet's apps/<app>.secrets.yml."),
+    config: z.array(z.string()).optional().describe("Config keys; their values come from the fleet's apps/<app>.yml."),
+});
+/** apps/<app>.yml and apps/<app>.secrets.yml: flat key → value. */
+export const appValuesSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]));

package/cli/dist/validate.js

@@ -0,0 +1,50 @@
+import { err, ok } from "./result.js";
+import { isAnsibleVariable, settings } from "./settings.js";
+/** Edit distance, for "did you mean". */
+const indices = (length) => [...Array(length).keys()];
+const distance = (a, b) => indices(b.length)
+    .reduce((row, j) => indices(a.length).reduce((next, i) => [
+    ...next,
+    Math.min((row[i + 1] ?? 0) + 1, (next[i] ?? 0) + 1, (row[i] ?? 0) + (a.charAt(i) === b.charAt(j) ? 0 : 1)),
+], [j + 1]), indices(a.length + 1))
+    .at(-1) ?? 0;
+const suggestion = (key, known) => {
+    const closest = known
+        .map((name) => ({ name, cost: distance(key, name) }))
+        .toSorted((x, y) => x.cost - y.cost)
+        .at(0);
+    return closest !== undefined && closest.cost <= Math.max(2, Math.floor(key.length / 4)) ? ` — did you mean '${closest.name}'?` : "";
+};
+/** The first problem Zod found, said for the file it is in. */
+const firstIssue = (file, error, known, unknownKey) => {
+    const issue = error.issues.at(0);
+    if (issue === undefined)
+        return `${file} is invalid`;
+    if (issue.code === "unrecognized_keys") {
+        const key = issue.keys.at(0) ?? "";
+        const where = issue.path.length === 0 ? "" : ` (in ${issue.path.join(".")})`;
+        return `${file}: '${key}' ${unknownKey}${where}${issue.path.length === 0 ? suggestion(key, known) : ""}`;
+    }
+    return `${file}: ${issue.path.length === 0 ? "" : `${issue.path.join(".")}: `}${issue.message}`;
+};
+const secretNames = settings.filter((each) => each.secret).map((each) => each.name);
+/**
+ * A settings file (vars.yml, defaults.yml) against its schema: a secret in it
+ * is refused first, then unknown keys and wrong types. Ansible's own variables
+ * are always allowed.
+ */
+export const checkSettings = (file, values, schema, known) => {
+    const leaked = Object.keys(values).find((key) => secretNames.includes(key));
+    if (leaked !== undefined)
+        return err(`${file}: '${leaked}' is a secret — it goes in secrets.yml`);
+    const own = Object.fromEntries(Object.entries(values).filter(([key]) => !isAnsibleVariable(key)));
+    const parsed = schema.safeParse(own);
+    return parsed.success ? ok(values) : err(firstIssue(file, parsed.error, known, "is not a setting"));
+};
+/** The names a kind's vars.yml may set. */
+export const knownSettings = (kind) => settings.filter((each) => !each.secret && (kind === undefined || each.kinds.includes(kind))).map((each) => each.name);
+/** A YAML document against a schema, for files whose keys are not settings (server.yml, app.yml). */
+export const checkShape = (file, values, schema) => {
+    const parsed = schema.safeParse(values);
+    return parsed.success ? ok(values) : err(firstIssue(file, parsed.error, [], "is not a key it knows"));
+};

package/compose/buildkit/buildkitd.toml

@@ -8,6 +8,13 @@
   # 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
+  # The cache shares the server's disk with everything else; unbounded, it
+  # filled alaz (27 GB). Collected down to maxUsedSpace, sooner when the disk
+  # has less than minFreeSpace left; never below reservedSpace.
+  gc = true
+  reservedSpace = "2GB"
+  maxUsedSpace = "10GB"
+  minFreeSpace = "20%"
 
 [registry."registry:5000"]
   http = true

package/compose/docker-compose.ci.yml

@@ -6,7 +6,7 @@
 
 services:
   registry:
-    image: registry:2.8.3
+    image: registry:2.8.3@sha256:a3d8aaa63ed8681a604f1dea0aa03f100d5895b6a58ace528858a7b332415373
     restart: unless-stopped
     environment:
       # registry-gc.sh deletes manifests nothing references any more.
@@ -30,7 +30,7 @@ services:
   # container, not the box.
   # ---------------------------------------------------------------------------
   buildkitd:
-    image: moby/buildkit:v0.34.0-rootless
+    image: moby/buildkit:v0.34.0-rootless@sha256:65eca3c01cd1180c8f64565c4e3c5983af5145818b0e6fa863385d099eb73855
     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

package/compose/docker-compose.yml

@@ -5,13 +5,15 @@
 
 services:
   traefik:
-    image: traefik:v3.7.14
+    image: traefik:v3.7.14@sha256:575fa15b135078fe5e50aa847987d96dbddd7b093c172429618404df73f3fa7c
     restart: unless-stopped
     ports:
       - "80:80"
       - "443:443"
+    # No Docker socket: containers are read through socket-proxy. A mount,
+    # even :ro, would be the whole Docker API, i.e. root on the host, for the
+    # one service the internet talks to.
     volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
       - ./traefik/traefik.yml:/etc/traefik/traefik.yml:ro
       - ./traefik/dynamic:/etc/traefik/dynamic:ro
       - ./traefik/certs:/certs:ro
@@ -19,6 +21,7 @@ services:
     networks:
       - public
       - internal
+      - socket
     labels:
       # The dashboard used to ride on an unauthenticated published :8080.
       # It speaks no auth of its own, which is exactly what forwardAuth is for.
@@ -29,6 +32,27 @@ services:
       - "traefik.http.routers.dashboard.service=api@internal"
       - "traefik.http.routers.dashboard.middlewares=authelia@file,security-headers@file"
 
+  # ---------------------------------------------------------------------------
+  # Traefik's view of Docker: the socket behind an allow-list. Read-only
+  # (POST off), and only containers, events, version and ping — what the
+  # Docker provider asks for. Reachable on platform-socket only, a network
+  # with no route out that nothing but Traefik joins.
+  # ---------------------------------------------------------------------------
+  socket-proxy:
+    image: tecnativa/docker-socket-proxy:v0.5.0@sha256:1f5038b54f06c3e18422902cf00ba21803d1c97805aae032e5e6673d532d3459
+    restart: unless-stopped
+    environment:
+      - CONTAINERS=1
+      - EVENTS=1
+      - VERSION=1
+      - PING=1
+      - POST=0
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    mem_limit: 64m
+    networks:
+      - socket
+
   # ---------------------------------------------------------------------------
   # Authelia — single sign-on for services that sit behind Traefik.
   #
@@ -36,7 +60,7 @@ services:
   # infinite redirect. The portal has to stay reachable to authenticate anyone.
   # ---------------------------------------------------------------------------
   authelia:
-    image: authelia/authelia:4.39.28
+    image: authelia/authelia:4.39.28@sha256:bd97cff4fcbf715b5ff1f9ae286afbe6033afce385302520b0368122d43a6f54
     restart: unless-stopped
     environment:
       - X_AUTHELIA_CONFIG=/config/configuration.yml
@@ -75,6 +99,10 @@ networks:
     name: platform-public
   internal:
     name: platform-internal
+  # Traefik and socket-proxy only; internal, so the proxy has no way out.
+  socket:
+    name: platform-socket
+    internal: true
 
 volumes:
   acme-data:

package/compose/traefik/traefik.yml

@@ -35,7 +35,8 @@ certificatesResolvers:
 
 providers:
   docker:
-    endpoint: "unix:///var/run/docker.sock"
+    # The read-only socket proxy (compose: socket-proxy), not the socket.
+    endpoint: "tcp://socket-proxy:2375"
     exposedByDefault: false
     network: platform-public
   file:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunuseon/kayra",
-  "version": "0.5.1",
+  "version": "0.7.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",
@@ -23,7 +23,8 @@
     "terraform/",
     "scripts/",
     "cloud-init.yml.tpl",
-    "hosts.conf"
+    "hosts.conf",
+    "schema/"
   ],
   "publishConfig": {
     "access": "public",
@@ -35,12 +36,14 @@
     "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'"
+    "test": "node --test 'cli/test/**/*.test.ts'",
+    "schemas": "node cli/scripts/schemas.ts"
   },
   "dependencies": {
     "@optique/core": "1.3.3",
     "@optique/run": "1.3.3",
-    "yaml": "2.9.1"
+    "yaml": "2.9.1",
+    "zod": "4.6.5"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",

package/schema/app-values.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "propertyNames": {
+    "type": "string"
+  },
+  "additionalProperties": {
+    "type": [
+      "string",
+      "number",
+      "boolean"
+    ]
+  },
+  "title": "apps/<app>.yml and apps/<app>.secrets.yml"
+}

package/schema/app.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The app's name, as in the server.yml entry."
+    },
+    "compose": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Compose files, relative to the app root, in order."
+    },
+    "subdomains": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Hostnames the app claims: <sub>.<domain>."
+    },
+    "secrets": {
+      "description": "Secret keys; their values come from the fleet's apps/<app>.secrets.yml.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "config": {
+      "description": "Config keys; their values come from the fleet's apps/<app>.yml.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "name",
+    "compose",
+    "subdomains"
+  ],
+  "additionalProperties": false,
+  "title": "app.yml"
+}