@yunuseon/kayra 0.0.0-stage → 0.5.0

package/compose/docker-compose.yml

@@ -0,0 +1,83 @@
+# =============================================================================
+# Platform base — Traefik reverse proxy + shared network
+# App-agnostic: knows nothing about what applications run on this platform.
+# =============================================================================
+
+services:
+  traefik:
+    image: traefik:v3.7.14
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    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
+      - acme-data:/acme
+    networks:
+      - public
+      - internal
+    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.
+      - "traefik.enable=true"
+      - "traefik.http.routers.dashboard.rule=Host(`traefik.${DOMAIN:-localhost}`)"
+      - "traefik.http.routers.dashboard.entrypoints=websecure"
+      - "traefik.http.routers.dashboard.tls.certresolver=le"
+      - "traefik.http.routers.dashboard.service=api@internal"
+      - "traefik.http.routers.dashboard.middlewares=authelia@file,security-headers@file"
+
+  # ---------------------------------------------------------------------------
+  # Authelia — single sign-on for services that sit behind Traefik.
+  #
+  # Deliberately NOT behind its own authelia@file middleware: that would be an
+  # infinite redirect. The portal has to stay reachable to authenticate anyone.
+  # ---------------------------------------------------------------------------
+  authelia:
+    image: authelia/authelia:4.39.28
+    restart: unless-stopped
+    environment:
+      - X_AUTHELIA_CONFIG=/config/configuration.yml
+      # Authelia does not expand ${VAR}; this filter is what makes
+      # {{ env "DOMAIN" }} work inside configuration.yml.
+      - X_AUTHELIA_CONFIG_FILTERS=template
+      - DOMAIN=${DOMAIN:-localhost}
+      - AUTH_POLICY=${AUTH_POLICY:-two_factor}
+      - AUTHELIA_SESSION_SECRET_FILE=/config/secrets/session
+      - AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE=/config/secrets/storage_encryption
+      # Empty in dev, which falls the notifier back to a file — see
+      # configuration.yml. The SMTP password is NOT an env var; it is read from
+      # /config/secrets/smtp_password by the config template.
+      - SMTP_ADDRESS=${AUTHELIA_SMTP_ADDRESS:-}
+      - SMTP_USERNAME=${AUTHELIA_SMTP_USERNAME:-}
+      - SMTP_SENDER=${AUTHELIA_SMTP_SENDER:-}
+    volumes:
+      - ./authelia:/config:ro
+      - authelia-data:/data
+    mem_limit: 128m
+    networks:
+      - internal
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=platform-internal"
+      - "traefik.http.routers.authelia.rule=Host(`auth.${DOMAIN:-localhost}`)"
+      - "traefik.http.routers.authelia.entrypoints=websecure"
+      - "traefik.http.routers.authelia.tls.certresolver=le"
+      - "traefik.http.services.authelia.loadbalancer.server.port=9091"
+
+# Two networks, so an app can reach Traefik's routes and nothing else of the
+# platform. Apps join platform-public; the platform's own services live on
+# platform-internal, where only Traefik joins them.
+networks:
+  public:
+    name: platform-public
+  internal:
+    name: platform-internal
+
+volumes:
+  acme-data:
+  # Passkeys live here. Losing this volume means every credential is gone and
+  # everyone re-enrols — back it up.
+  authelia-data:

package/compose/jenkins/Dockerfile

@@ -0,0 +1,40 @@
+# =============================================================================
+# Jenkins Controller — LTS with Docker CLI, Compose, buildctl and JCasC
+# =============================================================================
+
+FROM jenkins/jenkins:2.580.1-lts-jdk21
+
+USER root
+
+# renovate: datasource=github-releases depName=moby/buildkit
+ARG BUILDKIT_VERSION=v0.34.0
+
+# Install Docker CLI + Compose plugin
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+      ca-certificates curl gnupg jq && \
+    install -m 0755 -d /etc/apt/keyrings && \
+    curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \
+    chmod a+r /etc/apt/keyrings/docker.gpg && \
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
+      https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
+      > /etc/apt/sources.list.d/docker.list && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends \
+      docker-ce-cli docker-compose-plugin && \
+    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
+
+# Install plugins
+COPY plugins.txt /usr/share/jenkins/ref/plugins.txt
+RUN jenkins-plugin-cli --plugin-file /usr/share/jenkins/ref/plugins.txt
+
+# JCasC fragments are bind-mounted, not baked in; CASC_JENKINS_CONFIG is set in
+# compose. That keeps config out of the image and out of the jenkins-home volume.
+# notifyCommit without a token, but only to trigger polling: how Forgejo tells
+# Jenkins about a push, over platform-internal (Traefik does not route it).
+ENV JAVA_OPTS="-Djenkins.install.runSetupWizard=false -Dhudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL=disabled-for-polling"

package/compose/jenkins/casc/00-platform.yaml

@@ -0,0 +1,158 @@
+# =============================================================================
+# Jenkins Configuration as Code — platform fragment (app-agnostic).
+#
+# Owns:
+#   - Jenkins setup, security realm, authorization
+#   - The agent node
+#   - Git credentials (for cloning the app repo)
+#   - GitHub: push-webhook secret + API token for commit statuses
+#   - Jenkins URL
+#
+# Also owns the app-agnostic jobs: platform-registry-gc and rollback work off
+# the release records every app's <app>/deploy job writes (the platform
+# library's appDeploy) and start that job with a REF. platform-renovate exists
+# only where the server has repos to keep up to date (PLATFORM_RENOVATE).
+#
+# Does NOT own any app-specific credentials (Postgres, ...) or app pipelines.
+# Each app renders its own 10-<app>.yaml next to this file and applies it with
+# bin/jenkins-app-apply. JCasC merges every YAML in this directory.
+#
+# Git remote comes from the platform .env (rendered by Ansible).
+# =============================================================================
+
+jenkins:
+  systemMessage: "Platform CI/CD — Managed by JCasC"
+  numExecutors: 1
+
+  securityRealm:
+    local:
+      allowsSignup: false
+      users:
+        - id: "${JENKINS_ADMIN_USER:-admin}"
+          password: "${JENKINS_ADMIN_PASSWORD:-admin}"
+
+  authorizationStrategy:
+    loggedInUsersCanDoAnything:
+      allowAnonymousRead: false
+
+  nodes:
+    - permanent:
+        name: "builder"
+        labelString: "buildkit linux"
+        numExecutors: 2
+        remoteFS: "/home/jenkins/agent"
+        launcher:
+          inbound:
+            workDirSettings:
+              disabled: false
+              internalDir: "remoting"
+        retentionStrategy: "always"
+
+credentials:
+  system:
+    domainCredentials:
+      - credentials:
+          - usernamePassword:
+              scope: GLOBAL
+              id: "git-credentials"
+              description: "Git credentials for cloning repositories"
+              username: "git"
+              password: "${readFile:/run/platform-secrets/GIT_TOKEN}"
+          - string:
+              scope: GLOBAL
+              id: "github-token"
+              description: "Same PAT as git-credentials; needs Commit statuses: write"
+              secret: "${readFile:/run/platform-secrets/GIT_TOKEN}"
+          - string:
+              scope: GLOBAL
+              id: "renovate-token"
+              description: "PAT for Renovate: Contents + Pull requests read & write"
+              secret: "${readFile:/run/platform-secrets/RENOVATE_TOKEN}"
+          - string:
+              scope: GLOBAL
+              id: "github-webhook-secret"
+              description: "HMAC secret GitHub signs push webhooks with"
+              secret: "${GITHUB_WEBHOOK_SECRET:-}"
+
+unclassified:
+  # The pipeline every app runs. Trusted (outside the sandbox), loaded from
+  # PLATFORM_REF (the release tag, v<version>; a test server may set a branch) and jobs cannot
+  # pick another version, so a pushed app branch never changes what a pipeline
+  # does. See ci/jenkins-lib/.
+  globalLibraries:
+    libraries:
+      - name: "platform"
+        defaultVersion: "${PLATFORM_REF}"
+        allowVersionOverride: false
+        implicit: false
+        retriever:
+          modernSCM:
+            libraryPath: "ci/jenkins-lib/"
+            scm:
+              git:
+                remote: "${JENKINS_GIT_REPO}"
+                credentialsId: "git-credentials"
+  location:
+    url: "https://jenkins.${DOMAIN:-localhost}/"
+  # Webhook lands on /github-webhook/. Hooks are registered by hand in the
+  # repo settings, not managed from here.
+  gitHubPluginConfig:
+    configs:
+      - name: "GitHub"
+        apiUrl: "https://api.github.com"
+        credentialsId: "github-token"
+        manageHooks: false
+    hookSecretConfigs:
+      - credentialsId: "github-webhook-secret"
+
+# Platform jobs run pipelines from PLATFORM_REF of this repo, never from a pushed branch.
+jobs:
+  - script: |
+      def fromPlatform = { String path ->
+        return {
+          cpsScm {
+            scm {
+              git {
+                remote {
+                  url("${JENKINS_GIT_REPO}")
+                  credentials("git-credentials")
+                }
+                branch("${PLATFORM_REF}")
+              }
+            }
+            scriptPath(path)
+            lightweight(false)
+          }
+        }
+      }
+
+      pipelineJob("platform-registry-gc") {
+        displayName("Platform Registry GC")
+        description("Nightly: deletes registry images no recent release of any app references, then prunes the BuildKit cache and host images. See ci/registry-gc.sh.")
+        definition(fromPlatform("ci/registry-gc.Jenkinsfile"))
+        triggers {
+          cron("H 3 * * *")
+        }
+      }
+
+      pipelineJob("rollback") {
+        displayName("Rollback")
+        description("Redeploys an earlier release of an app: pick the app, pick a release, done. Hands the SHA to <app>/deploy.")
+        definition(fromPlatform("ci/rollback.Jenkinsfile"))
+      }
+
+      if ("${PLATFORM_RENOVATE:-false}" == "true") {
+        pipelineJob("platform-renovate") {
+          displayName("Platform Renovate")
+          description("On renovate_schedule (weekly by default): opens PRs that bump pinned versions. Config: renovate.json. See ci/renovate.Jenkinsfile.")
+          // Declared here as well: a JCasC reload regenerates the job and drops
+          // parameters only the pipeline declares.
+          parameters {
+            booleanParam("DRY_RUN", false, "Log what would change, open no PRs")
+          }
+          definition(fromPlatform("ci/renovate.Jenkinsfile"))
+          triggers {
+            cron("${RENOVATE_SCHEDULE:-H 4 * * 1}")
+          }
+        }
+      }

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.5.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