coulomb/railiance-apps
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clarify app scope and plan forge extraction

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-05 00:56:33 +02:00
parent 179b87e244
commit e0f9a08b1c
4 changed files with 872 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

232
SCOPE.md
View File

@@ -1,85 +1,218 @@
# SCOPE
> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.
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 layer of the Railiance OAS Stack — owns application Helm releases and Kubernetes manifests for user-facing services (Gitea, coulomb services, web frontends).
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 structured as five independent repos, one per OAS (Open Application Stack) layer. This repo is S5 — the top layer. It owns application-level deployments: Helm values and manifests for Gitea, coulomb services, APIs, and web portals. It depends on S1–S4 being operational before it can do anything.
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
- Application Helm releases: Gitea, coulomb services, web portals, APIs
- Kubernetes manifests for user-facing workloads
- Application-level configuration and deployment orchestration
- 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-level concerns → railiance-infra (S1)
- Kubernetes runtime → railiance-cluster (S2)
- Platform services (PostgreSQL, caches, storage) → railiance-platform (S3)
- Developer tooling (CI/CD, portals) → railiance-enablement (S4)
- No re-configuration of lower layers from this repo
- 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 updating user-facing applications in the Railiance stack
- S1–S4 are all operational and it's time to deploy workloads
- 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 yet operational (pre-conditions not met)
- Infrastructure, cluster, or platform work needed (wrong layer)
- No user-facing applications to deploy
- 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 State
## Current Implementation Surface
- Status: active (Gitea Helm values now owned by S5; boundary violation resolved)
- Implementation: Gitea is deployed and operational. Helm values (`helm/gitea-values.sops.yaml`) are now managed from this repo (S5) — moved from railiance-cluster in RAIL-HO-WP-0004-T06. Gitea uses an external cnpg database (`gitea-db` in the `databases` namespace) and standalone Valkey.
- Stability: Gitea stable; S5 layer now owns the Gitea deployment lifecycle
- Usage: Gitea serves as the git hosting platform for all Railiance and Custodian repos
- 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`:
```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) → this repo (S5)
- Downstream consumers: end users accessing Gitea, coulomb services, web portals
- Often used with: railiance-platform (database/cache backends), net-kingdom (identity for apps)
---
## Terminology
- Preferred terms: OAS Stack Level S5, workloads, experience endpoints, boundary rule
- Potentially confusing terms: "S5" is a stack level designation, not a version
- 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` (S3) — provides database, cache, identity services consumed by S5 apps
- `railiance-enablement` (S4) — provides CI/CD and templates that S5 uses
- `railiance-cluster` (S2) — Kubernetes runtime where S5 workloads run
- `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.
---
@@ -87,16 +220,29 @@ Railiance is structured as five independent repos, one per OAS (Open Application
```capability
type: infrastructure
title: Application workload deployment (Gitea, coulomb services)
description: Deploy and manage user-facing applications — Gitea, coulomb services, APIs, and web portals — as Helm releases on the Railiance Kubernetes cluster.
keywords: [gitea, coulomb, webapp, helm, application, deployment, workload]
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]
```
```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
- Start with: `CLAUDE.md` (session protocol, boundary rules)
- Key files / directories: `workplans/` (currently empty), `Makefile`
- Pre-conditions: all four lower layers (S1–S4) must be converged and verified
- Key files: `helm/gitea-values.sops.yaml` (Gitea Helm values, SOPS-encrypted), `releases/gitea/values.yaml` (legacy plain values — superseded)
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.