coulomb/railiance-apps
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a29a6ec141a698427cc68146e72dfe5d32f2265b
railiance-apps/SCOPE.md

10 KiB
Raw Blame History

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 the current Gitea/registry surface 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

  • Transitional Gitea compatibility wrappers:
    • make gitea-deploy;
    • make gitea-ingress-deploy;
    • make gitea-status;
    • each delegates to /home/worsch/railiance-forge.
  • App-side registry consumption pointers:
    • docs/gitea-container-registry.md;
    • docs/gitea-package-registry.md;
    • canonical operating docs in /home/worsch/railiance-forge/docs/.
  • 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 keeps transitional Makefile wrappers only.
  • The Gitea container and Python package registry paths are verified. Canonical registry operating docs now live in railiance-forge; app-side files here are compatibility pointers.
  • 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

  • S5 app docs should continue shedding residual forge-runtime details and link to forge-owned operating contracts.
  • 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:

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 unless a command explicitly delegates to railiance-forge for current Gitea operation.

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

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, gitea, registry, helm, django, vergabe-teilnahme, workload, deployment]

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, start with /home/worsch/railiance-forge/docs/gitea-container-registry.md and /home/worsch/railiance-forge/docs/gitea-package-registry.md; the local files are compatibility pointers.
  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 and make check-sops before deploy work.
Reference in New Issue View Git Blame Copy Permalink