# SCOPE This file defines what `railiance-apps` owns, when to use it, and where its boundaries stop. Last reviewed: 2026-06-05 --- ## One-liner S5 Workloads & Experience Endpoints for Railiance: application Helm releases, Kubernetes workload manifests, app deployment guardrails, and operator runbooks for user-facing services such as `vergabe-teilnahme`. --- ## Core Idea Railiance is organized as layered repositories for the Open Application Stack. This repository owns the S5 application deployment surface. It does not build the lower platform; it takes already-converged infrastructure, cluster, platform services, and enablement paths, then ships user-facing workloads on top of them. The practical contract is: 1. lower layers provide runtime primitives and platform services, 2. this repo owns application release configuration and app-level manifests, 3. operator docs and checks here make those releases repeatable, 4. source application repos own their app code, package metadata, and image build pipelines. --- ## Intent Comparison `INTENT.md` now defines the stable purpose of this repo as the S5 application workload layer: turning platform capabilities into reliable, user-facing Railiance services with repeatable release operations. Compared with that intent, the current implementation is aligned around: - keep S5 application deployments portable across operators, CI, and remote builders; - keep application release concerns in S5 while respecting S1-S4 ownership; - provide enough runbook and guardrail coverage that the next app does not rediscover the same deployment traps; - consume forge-owned source and registry capabilities through the `railiance-forge` boundary instead of owning forge runtime state in S5. The remaining gap is not the absence of intent; it is turning the first-app lessons into reusable S5 app release patterns. --- ## In Scope - Consumption of forge-owned source and registry capabilities from S5 app release docs and values, without owning forge runtime configuration. - `vergabe-teilnahme` as the first concrete S5 application release: - chart in `charts/vergabe-teilnahme/`; - values in `helm/vergabe-teilnahme-values.yaml`; - ingress in `manifests/vergabe-teilnahme-ingress.yaml`; - Makefile targets for deploy, status, migrations, seed, logs, and DB URL secret rebuilds. - Application deployment operator guardrails: - `make check-tools`; - `make check-sops`; - `make k8s-server-dry-run`; - `.gitea/workflows/manifest-server-dry-run.yaml`; - scripts under `tools/`. - S5 app runbooks and recipes in `docs/`, especially: - `docs/vergabe-teilnahme.md`; - `docs/django-on-railiance.md`; - `docs/operator-setup.md`; - `docs/operator-recipes.md`. - Repo-local workplan files under `workplans/`. --- ## Out of Scope - OS or host provisioning: `railiance-infra`. - Kubernetes runtime, ingress controller primitives, and cluster-level routing: `railiance-cluster`. - Platform databases, shared backup primitives, object storage, caches, and durable platform services: `railiance-platform`. - CI/CD systems, source templates, and developer portal enablement outside the S5 app release surface: `railiance-enablement`. - Application source code and package build metadata for deployed apps: source application repos such as `vergabe-teilnahme`. - Publishing `issue-core` itself or regenerating `vergabe-teilnahme` package locks: `issue-core` and `vergabe-teilnahme` own those release artifacts. - Secret value custody. This repo may reference SOPS files and Kubernetes Secret names, but it must not commit decrypted values or secret material. --- ## Relevant When - Consuming already-published registry artifacts from S5 app releases. - Deploying or upgrading `vergabe-teilnahme` on Railiance. - Adding another user-facing S5 application release. - Debugging app-level Helm values, app ingress, app probes, app secrets, or app-specific runbook behavior. - Turning lessons from an app deployment into reusable operator recipes. --- ## Not Relevant When - S1-S4 are not converged enough for S5 workloads to deploy. - The work requires platform database provisioning, backup controller setup, or shared storage changes. - The work is application source-code behavior rather than release wiring. - The work is forge runtime, registry retention, runner substrate, or Forgejo production migration design rather than S5 app release operation. - The work requires secret custody, credential generation, or token storage outside approved operator paths. --- ## Current State - Gitea is deployed and operational as the current forge. Its deploy-capable Helm/SOPS/manifests now live in `railiance-forge`; this repo no longer keeps Gitea deploy/status wrappers or registry pointer docs. - The Gitea container and Python package registry paths are verified. Canonical registry operating docs live in `railiance-forge`; S5 runbooks link to those docs directly when app releases consume forge artifacts. - The final source-of-truth decision for forge ownership is recorded in `docs/forge-source-of-truth-decision.md`. - The `issue-core` migration is still blocked on publishing `issue-core==0.2.0` with package credentials in the `issue-core` repo and refreshing the `vergabe-teilnahme` lock in its source repo. - `vergabe-teilnahme` is represented as a local Helm chart plus values, ingress, Makefile targets, and an operator runbook. - Several deployment lessons are now repo-local guardrails: URL-encoded database URL secret creation, Django probe Host headers, operator tool checks, SOPS age-key checks, server-side manifest dry-run, and persistent-pod smoke testing. - Workplan files are now the source artifacts for planned work. State Hub indexes those files as workstreams and task blocks after `make fix-consistency REPO=railiance-apps`. --- ## Known Gaps And Opportunities - The first-app lessons from `vergabe-teilnahme` are documented, but there is no reusable "new S5 app release checklist" yet. - The manifest dry-run workflow assumes access to a representative cluster and CRDs. Forge-owned runner labels, placement, and credential prerequisites are defined in `/home/worsch/railiance-forge/docs/ci-runner-actions-gitops-ownership.md`; the app-side workflow behavior still needs explicit S5 readiness docs. - App-level backup and restore responsibilities need clearer handoff contracts with `railiance-platform`, especially for shared CNPG databases consumed by S5 apps. Forge artifact restore and secret-custody evidence is defined in `/home/worsch/railiance-forge/docs/backup-restore-secret-handoff.md`. - Forge release-readiness evidence that S5 app runbooks may cite is defined in `/home/worsch/railiance-forge/docs/observability-operating-evidence.md`. --- ## Workplan And State Hub Model Work items originate as files in this repository under `workplans/`. State Hub does not own the canonical file; it indexes workplan files as hub workstreams and indexes each fenced task block as a hub task. After editing workplan files, run from `~/state-hub`: ```bash make fix-consistency REPO=railiance-apps ``` Use "workplan" for the repo file and "workstream" for the State Hub row created from that file. --- ## How It Fits - Upstream dependencies: `railiance-infra` (S1) -> `railiance-cluster` (S2) -> `railiance-platform` (S3) -> `railiance-enablement` (S4) -> `railiance-apps` (S5). - Downstream consumers: operators deploying S5 workloads, users accessing deployed apps, and source repos that need a governed deployment target. - Frequent collaborators: `railiance-platform` for databases and backup contracts, `net-kingdom` for identity integrations, `issue-core` for task/package coordination, and source app repos such as `vergabe-teilnahme`. --- ## Terminology - Preferred terms: S5 app release, application workload, app runbook, release values, deployment guardrail, smoke evidence. - Forge terms: source forge, registry, package registry, runner substrate, and artifact evidence belong to `railiance-forge`; this repo consumes those capabilities. - Potentially confusing terms: "deployment" here means app release deployment. Forge runtime deployment and registry operation belong to `railiance-forge`. --- ## Related / Overlapping - `railiance-platform`: shared CNPG clusters, backup primitives, object storage, and other platform services consumed by S5 apps. - `railiance-forge`: current Gitea operation, future Forgejo migration, registries, runners, artifact retention, and forge evidence. - `railiance-enablement`: CI/CD templates and developer paved paths used by S5 releases. - `railiance-cluster`: Kubernetes runtime, ingress controllers, cert-manager, and cluster networking. - `vergabe-teilnahme`: source Django app, package lock, Dockerfile, and app code. - `issue-core`: package release required by `vergabe-teilnahme` and future apps. --- ## Provided Capabilities ```capability type: infrastructure title: S5 application workload deployment description: Deploy and operate user-facing Railiance applications as Helm releases and Kubernetes manifests, including app release guardrails and the first Django S5 app release. keywords: [railiance, s5, registry-consumer, helm, django, vergabe-teilnahme, workload, deployment] ``` ```capability type: operations title: S5 deployment guardrails and runbooks description: Provide operator checks, SOPS verification, server-side manifest dry-runs, smoke-test patterns, and app-specific deployment runbooks for Railiance S5 workloads. keywords: [operator, runbook, sops, cnpg, dry-run, smoke-test, deployment] ``` --- ## Getting Oriented 1. Read `AGENTS.md` for session protocol and State Hub conventions. 2. Read `INTENT.md` for the stable purpose of the S5 layer. 3. Read this file for scope and boundaries. 4. Read the active files in `workplans/`. 5. For Gitea registry work, use the forge-owned docs directly: `/home/worsch/railiance-forge/docs/gitea-container-registry.md` and `/home/worsch/railiance-forge/docs/gitea-package-registry.md`. 6. For `vergabe-teilnahme`, start with `docs/vergabe-teilnahme.md`, then inspect `charts/vergabe-teilnahme/`, `helm/vergabe-teilnahme-values.yaml`, and `manifests/vergabe-teilnahme-ingress.yaml`. 7. Run `make check-tools` before deploy work. Run `SOPS_SENTINEL= make check-sops` when app release work touches encrypted SOPS files.