@yunuseon/kayra 0.8.1 → 0.9.0

package/ansible/roles/platform/tasks/main.yml

@@ -347,3 +347,12 @@
     chdir: "{{ platform_dir }}"
   when: platform_files.results | selectattr('item', 'eq', 'buildkit/') | selectattr('changed') | list | length > 0
   changed_when: true
+
+# Authelia reads its configuration once at startup; the user database it
+# watches itself (authentication_backend.file.watch).
+- name: Restart Authelia when its config changed
+  ansible.builtin.command: docker compose restart authelia
+  args:
+    chdir: "{{ platform_dir }}"
+  when: platform_files.results | selectattr('item', 'eq', 'authelia/configuration.yml') | selectattr('changed') | list | length > 0
+  changed_when: true

package/cli/dist/brand.js

@@ -34,5 +34,6 @@ const minting = (metavar, mint, placeholder) => ({
     format: (value) => value,
 });
 export const appNameParser = minting("APP", appName, "app");
+export const serverNameParser = minting("SERVER", serverName, "server");
 export const domainParser = minting("DOMAIN", domain, "example.com");
 export const subdomainParser = minting("SUBDOMAIN", subdomain, "www");

package/cli/dist/cli.js

@@ -2,10 +2,12 @@ import { command, constant, multiple, object, option, optional, or } from "@opti
 import { message } from "@optique/core/message";
 import { argument } from "@optique/core/primitives";
 import { choice, string } from "@optique/core/valueparser";
-import { appNameParser, domainParser, subdomainParser } from "./brand.js";
+import { appNameParser, domainParser, serverNameParser, subdomainParser } from "./brand.js";
 /** The arguments kayra takes; server names are the fleet's, so they complete and are checked while parsing. */
 export const parser = (fleet) => {
-    const server = argument(choice(fleet.servers.map((each) => each.name), { metavar: "SERVER" }));
+    const [first, ...rest] = fleet.servers.map((each) => each.name);
+    // Outside a fleet there is no name to offer; main refuses every server command there.
+    const server = argument(first === undefined ? serverNameParser : choice([first, ...rest], { metavar: "SERVER" }));
     // eslint-disable-next-line functional/prefer-immutable-types -- Optique's Message is readonly only at the top
     const onServer = (name, brief) => command(name, object({ name: constant(name), server }), { brief });
     return object({
@@ -14,11 +16,13 @@ export const parser = (fleet) => {
         // On one server
         or(onServer("up", message `Provision, set up everything, point /etc/hosts at it.`), onServer("provision", message `Create or update the machine (target home: build the image to import).`), onServer("deploy", message `Host setup and every app, no provisioning.`), onServer("setup", message `The host layer only: the playbook for the server's kind.`), onServer("plan", message `What provision and setup would change, changing nothing (OpenTofu plan, Ansible check mode).`), onServer("apps", message `Make the server's apps match server.yml: register each, remove the rest (data kept).`), onServer("hosts", message `Point the domain at a multipass VM in /etc/hosts (sudo).`), command("ssh", object({ name: constant("ssh"), server, remote: multiple(argument(string({ metavar: "COMMAND" }))) }), { brief: message `SSH into the server, or run a command there (after --).` }), onServer("down", message `Destroy the machine.`), onServer("adopt", message `Once, for a server we did not create: add the deploy user as root.`), command("backup", command("test", object({ name: constant("backup test"), server })), {
             brief: message `Restore the latest backup to a scratch dir, check it, delete it.`,
-        }), command("app", or(command("purge", object({ name: constant("app purge"), server, app: argument(appNameParser) }), {
+        }), command("app", or(command("check", object({ name: constant("app check"), dir: optional(argument(string({ metavar: "DIR" }))) }), {
+            brief: message `In an app's repository: what the platform checks at deploy (app.yml, images, compose policy). No fleet needed.`,
+        }), command("purge", object({ name: constant("app purge"), server, app: argument(appNameParser) }), {
             brief: message `Delete a removed app's volumes: its data, irreversibly.`,
         }), command("runs", object({ name: constant("app runs"), server, app: argument(appNameParser) }), {
             brief: message `The app's latest runs: id, result, commit, why.`,
-        }), command("logs", object({ name: constant("app logs"), server, app: argument(appNameParser), more: optional(argument(string({ metavar: "RUN" }))) }), { brief: message `A run's log, the newest unless named.` }), command("deploy", object({ name: constant("app deploy"), server, app: argument(appNameParser), more: optional(argument(string({ metavar: "REF" }))) }), { brief: message `Build and deploy a branch, tag or commit (default: the app's ref).` }), command("rollback", object({ name: constant("app rollback"), server, app: argument(appNameParser), more: optional(argument(string({ metavar: "SHA" }))) }), { brief: message `List earlier releases, or deploy one of them again.` })), { brief: message `An app on a server: its runs, logs, deploys, rollbacks, and purging its data.` }), command("job", object({
+        }), command("logs", object({ name: constant("app logs"), server, app: argument(appNameParser), more: optional(argument(string({ metavar: "RUN" }))) }), { brief: message `A run's log, the newest unless named.` }), command("deploy", object({ name: constant("app deploy"), server, app: argument(appNameParser), more: optional(argument(string({ metavar: "REF" }))) }), { brief: message `Build and deploy a branch, tag or commit (default: the app's ref).` }), command("rollback", object({ name: constant("app rollback"), server, app: argument(appNameParser), more: optional(argument(string({ metavar: "SHA" }))) }), { brief: message `List earlier releases, or deploy one of them again.` })), { brief: message `An app: check it before a push, or on a server its runs, logs, deploys, rollbacks, and purging its data.` }), command("job", object({
             name: constant("job"),
             server,
             job: argument(choice(["gc", "renovate"], { metavar: "JOB" })),

package/cli/dist/commands/app-check.js

@@ -0,0 +1,35 @@
+import { appName, within } from "../brand.js";
+import { yamlOf } from "../fleet.js";
+import { run } from "../plan.js";
+import { err, flatMap, map } from "../result.js";
+import { appManifestSchema } from "../settings.js";
+import { checkShape } from "../validate.js";
+const mapError = (result, f) => result.ok ? result : err(f(result.error));
+const tool = (program, hint) => ({
+    kind: "check",
+    label: `${program} is installed`,
+    probe: { kind: "on-path", program },
+    hint,
+    onFailure: "stop",
+});
+/**
+ * In an app's own repository, before a push: what the platform checks when it
+ * deploys the app — app.yml against its schema here, then app-check.sh (the
+ * image plan and the compose policy, the same scripts the builder and the
+ * deployer run). Needs no fleet and no server.
+ */
+export const appCheck = (kayra, root, manifest) => {
+    if (manifest === undefined)
+        return err(`no app.yml in ${root}`);
+    const shaped = flatMap(flatMap(mapError(yamlOf(manifest), (problem) => `app.yml ${problem}`), (values) => checkShape("app.yml", values, appManifestSchema)), (values) => {
+        const parsed = appManifestSchema.safeParse(values);
+        return parsed.success ? appName(parsed.data.name) : err("app.yml: invalid");
+    });
+    return map(shaped, () => [
+        tool("git", "brew install git"),
+        tool("jq", "brew install jq"),
+        tool("yq", "brew install yq"),
+        tool("docker", "the docker CLI with Compose; no daemon is needed"),
+        run(["bash", within(kayra, "scripts", "local", "app-check.sh"), root]),
+    ]);
+};

package/cli/dist/main.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 import { run } from "@optique/run";
 import { createInterface } from "node:readline/promises";
-import { absolutePath, kayraRoot, within } from "./brand.js";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { absolutePath, fleetRoot, kayraRoot, within } from "./brand.js";
+import { appCheck } from "./commands/app-check.js";
 import { parser } from "./cli.js";
 import { doctor } from "./commands/doctor.js";
 import * as server from "./commands/server.js";
@@ -81,12 +84,28 @@ const fail = (message) => {
     console.error(`kayra: ${message}`);
     process.exit(1);
 };
-const fleet = flatMap(findFleetRoot(here.value), loadFleet);
+const found = flatMap(findFleetRoot(here.value), loadFleet);
+// Outside a fleet only `app check` runs: it works in an app's repository.
+const fleet = found.ok ? found : ok({ root: fleetRoot(here.value), servers: [] });
 if (!fleet.ok)
     fail(fleet.error);
 else {
     const args = run(parser(fleet.value), { programName: "kayra", help: "both", completion: "both" });
-    if (args.command.name === "status") {
+    if (!found.ok && args.command.name !== "app check")
+        fail(found.error);
+    if (args.command.name === "app check") {
+        const root = absolutePath(resolve(here.value, args.command.dir ?? "."));
+        const manifestPath = root.ok ? join(root.value, "app.yml") : "";
+        const steps = flatMap(root, (dir) => appCheck(kayra, dir, existsSync(manifestPath) ? readFileSync(manifestPath, "utf8") : undefined));
+        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;
+    }
+    else if (args.command.name === "status") {
         (await status(fleet.value)).forEach(io.out);
     }
     else if (args.command.name === "validate") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunuseon/kayra",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "A self-hosted app platform and the CLI that runs it: Traefik, Authelia, a registry, rootless BuildKit and a small deployer per server, set up with OpenTofu and Ansible.",
   "license": "MIT",
   "author": "Yunus Öztürk",

package/scripts/local/app-check.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# =============================================================================
+# app-check.sh <app-root> — what the platform checks when it deploys an app,
+# checked in the app's own repository, before a push: run by `kayra app
+# check`, which has checked app.yml against its schema first.
+#
+#   - app.yml's compose files exist, inside the app; its subdomains are not
+#     the platform's (hosts.conf)
+#   - every docker/image.json: its image in the app's namespace, a commit
+#     touching its inputs (resolve-images.sh --plan, as the builder runs it)
+#   - the compose config those files resolve to passes the compose policy
+#     (compose-policy.sh, as the deployer runs it), with placeholder values for
+#     the images, config and secrets, and hosts under example.test
+#
+# Needs git, jq, yq and the docker CLI with Compose (no daemon: `compose
+# config` only reads files). Written for macOS's bash 3.2 too: no mapfile.
+# =============================================================================
+set -euo pipefail
+
+KAYRA_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+root="$(cd "${1:?Usage: app-check.sh <app-root>}" && pwd)"
+manifest="${root}/app.yml"
+domain=example.test
+failed=0
+
+fail() { echo "✗ $*"; failed=1; }
+pass() { echo "✓ $*"; }
+
+name="$(yq -r '.name' "$manifest")"
+files="$(yq -r '.compose[]' "$manifest")"
+subdomains="$(yq -r '.subdomains[]' "$manifest")"
+reserved="$(awk '!/^[[:space:]]*(#|$)/ {print $1}' "${KAYRA_ROOT}/hosts.conf")"
+
+# ── app.yml ─────────────────────────────────────────────────────────────────
+while IFS= read -r file; do
+    case "$file" in
+        /*|..|../*|*/../*|*/..) fail "compose file ${file} is outside the app" ;;
+        *) [ -f "${root}/${file}" ] || fail "compose file ${file} does not exist" ;;
+    esac
+done <<< "$files"
+while IFS= read -r sub; do
+    if grep -qxF -- "$sub" <<< "$reserved"; then fail "subdomain ${sub} is the platform's"; fi
+done <<< "$subdomains"
+[ "$failed" = 0 ] && pass "app.yml: compose $(paste -sd' ' - <<< "$files") · subdomains $(paste -sd' ' - <<< "$subdomains")"
+
+# ── Images ──────────────────────────────────────────────────────────────────
+if plan="$(bash "${KAYRA_ROOT}/scripts/platform/resolve-images.sh" "$name" "$root" --plan)"; then
+    pass "images: $(awk -F'\t' '{printf "%s%s", sep, $1; sep=", "}' <<< "$plan")"
+else
+    fail "images: resolve-images.sh refused the image plan (above)"
+fi
+[ "$failed" = 0 ] || exit 1
+
+# ── Compose policy ──────────────────────────────────────────────────────────
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+{
+    echo "COMPOSE_PROJECT_NAME=${name}"
+    echo "DOMAIN=${domain}"
+    yq -r '.config // [] | .[] | . + "=check"' "$manifest"
+    awk -F'\t' 'NF == 3 {print $2 "=" $3}' <<< "$plan"
+} > "${work}/.env"
+# Secrets reach compose as the deploy's environment, never through a file.
+while IFS= read -r key; do
+    [ -z "$key" ] || export "${key}=check"
+done <<< "$(yq -r '.secrets // [] | .[]' "$manifest")"
+
+set -- docker compose -p "$name" --project-directory "$root" --env-file "${work}/.env"
+while IFS= read -r file; do set -- "$@" -f "${root}/${file}"; done <<< "$files"
+"$@" config --no-env-resolution --format json > "${work}/config.json" \
+    || { fail "compose: docker compose config failed (above)"; exit 1; }
+
+set --
+while IFS= read -r sub; do set -- "$@" "${sub}.${domain}"; done <<< "$subdomains"
+if violations="$(bash "${KAYRA_ROOT}/scripts/platform/compose-policy.sh" "$name" "$@" < "${work}/config.json")"; then
+    pass "compose policy: admitted"
+else
+    while IFS= read -r line; do fail "compose policy: ${line}"; done <<< "$violations"
+fi
+exit "$failed"