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

9.7 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-04

One-liner

S5 Workloads & Experience Endpoints for Railiance: application Helm releases, Kubernetes workload manifests, registry enablement, and operator runbooks for user-facing services such as Gitea and 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;
  • use Gitea as the current forge and package registry until the Forgejo production migration supersedes it.

The remaining gap is not the absence of intent; it is turning the first-app lessons into reusable S5 app release patterns.

In Scope

  • Gitea as the current S5 forge workload:
    • Helm release values in helm/gitea-values.sops.yaml;
    • non-secret registry overlay in helm/gitea-registry-values.yaml;
    • ingress manifest in manifests/gitea-ingress.yaml;
    • make gitea-deploy, make gitea-status, and related operator checks.
  • Gitea package registry enablement and operator documentation:
    • container registry path and smoke evidence;
    • Python package registry endpoint and consumer guidance;
    • registry settings applied as application Helm 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/gitea-container-registry.md;
    • docs/gitea-package-registry.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

  • Deploying or upgrading Gitea as the current S5 forge workload.
  • Enabling or verifying Gitea package registry behavior for S5 consumers.
  • 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 Forgejo production migration design rather than current Gitea operation.
  • The work requires secret custody, credential generation, or token storage outside approved operator paths.

Current Implementation Surface

  • Gitea is deployed and operational as the current forge. Its S5 Helm values live here, and registry settings are layered through helm/gitea-registry-values.yaml.
  • The Gitea container registry path is verified and documented. Package blobs currently land on the Gitea shared PVC, so storage growth and backup/retention posture remain important follow-up concerns.
  • The Gitea Python package registry endpoint is enabled and documented. 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

  • docs/vergabe-teilnahme.md still references the old local issue-core Docker build-context path in the image promotion section. It needs to be updated after the package registry handoff is fully closed.
  • Gitea package blob storage is operational but not yet tied to an explicit retention, capacity, and restore posture.
  • 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. Its operating requirements should be made explicit for future runners.
  • App-level backup and restore responsibilities need clearer handoff contracts with railiance-platform, especially for shared CNPG databases consumed by S5 apps.

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.

Related / Overlapping

  • railiance-platform: shared CNPG clusters, backup primitives, object storage, and other platform services consumed by S5 apps.
  • railiance-enablement: CI/CD and templates 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 Gitea, registry enablement, 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 docs/gitea-container-registry.md and 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 and make check-sops before deploy work.
Reference in New Issue View Git Blame Copy Permalink