261 lines
9.9 KiB
Markdown
261 lines
9.9 KiB
Markdown
# 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. 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) ->
|
|
`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
|
|
|
|
```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, 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
|
|
|
|
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.
|