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

Point app registry docs at railiance-forge

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-05 12:07:26 +02:00
parent ec22928e24
commit c8e50e6e84
6 changed files with 85 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
SCOPE.md
View File

@@ -3,15 +3,15 @@
This file defines what `railiance-apps` owns, when to use it, and where its This file defines what `railiance-apps` owns, when to use it, and where its
boundaries stop. boundaries stop.
Last reviewed: 2026-06-04 Last reviewed: 2026-06-05
--- ---
## One-liner ## One-liner
S5 Workloads & Experience Endpoints for Railiance: application Helm releases, S5 Workloads & Experience Endpoints for Railiance: application Helm releases,
Kubernetes workload manifests, registry enablement, and operator runbooks for Kubernetes workload manifests, transitional Gitea release configuration, and
user-facing services such as Gitea and `vergabe-teilnahme`. operator runbooks for user-facing services such as `vergabe-teilnahme`.
--- ---
@@ -45,8 +45,8 @@ intent, the current implementation is aligned around:
- keep application release concerns in S5 while respecting S1-S4 ownership; - keep application release concerns in S5 while respecting S1-S4 ownership;
- provide enough runbook and guardrail coverage that the next app does not - provide enough runbook and guardrail coverage that the next app does not
rediscover the same deployment traps; rediscover the same deployment traps;
- use Gitea as the current forge and package registry until the Forgejo - consume the current Gitea/registry surface through the emerging
production migration supersedes it. `railiance-forge` boundary while live deploy-capable files are still moving.
The remaining gap is not the absence of intent; it is turning the first-app The remaining gap is not the absence of intent; it is turning the first-app
lessons into reusable S5 app release patterns. lessons into reusable S5 app release patterns.
@@ -55,15 +55,16 @@ lessons into reusable S5 app release patterns.
## In Scope ## In Scope
- Gitea as the current S5 forge workload: - Gitea as a transitional S5-managed workload until `railiance-forge` completes
the deploy-capable migration:
- Helm release values in `helm/gitea-values.sops.yaml`; - Helm release values in `helm/gitea-values.sops.yaml`;
- non-secret registry overlay in `helm/gitea-registry-values.yaml`; - non-secret registry overlay in `helm/gitea-registry-values.yaml`;
- ingress manifest in `manifests/gitea-ingress.yaml`; - ingress manifest in `manifests/gitea-ingress.yaml`;
- `make gitea-deploy`, `make gitea-status`, and related operator checks. - `make gitea-deploy`, `make gitea-status`, and related operator checks.
- Gitea package registry enablement and operator documentation: - App-side registry consumption pointers:
- container registry path and smoke evidence; - `docs/gitea-container-registry.md`;
- Python package registry endpoint and consumer guidance; - `docs/gitea-package-registry.md`;
- registry settings applied as application Helm configuration. - canonical operating docs in `/home/worsch/railiance-forge/docs/`.
- `vergabe-teilnahme` as the first concrete S5 application release: - `vergabe-teilnahme` as the first concrete S5 application release:
- chart in `charts/vergabe-teilnahme/`; - chart in `charts/vergabe-teilnahme/`;
- values in `helm/vergabe-teilnahme-values.yaml`; - values in `helm/vergabe-teilnahme-values.yaml`;
@@ -78,8 +79,6 @@ lessons into reusable S5 app release patterns.
- scripts under `tools/`. - scripts under `tools/`.
- S5 app runbooks and recipes in `docs/`, especially: - S5 app runbooks and recipes in `docs/`, especially:
- `docs/vergabe-teilnahme.md`; - `docs/vergabe-teilnahme.md`;
- `docs/gitea-container-registry.md`;
- `docs/gitea-package-registry.md`;
- `docs/django-on-railiance.md`; - `docs/django-on-railiance.md`;
- `docs/operator-setup.md`; - `docs/operator-setup.md`;
- `docs/operator-recipes.md`. - `docs/operator-recipes.md`.
@@ -108,7 +107,7 @@ lessons into reusable S5 app release patterns.
## Relevant When ## Relevant When
- Deploying or upgrading Gitea as the current S5 forge workload. - Deploying or upgrading Gitea as the current S5 forge workload.
- Enabling or verifying Gitea package registry behavior for S5 consumers. - Consuming already-published registry artifacts from S5 app releases.
- Deploying or upgrading `vergabe-teilnahme` on Railiance. - Deploying or upgrading `vergabe-teilnahme` on Railiance.
- Adding another user-facing S5 application release. - Adding another user-facing S5 application release.
- Debugging app-level Helm values, app ingress, app probes, app secrets, or - Debugging app-level Helm values, app ingress, app probes, app secrets, or
@@ -123,8 +122,8 @@ lessons into reusable S5 app release patterns.
- The work requires platform database provisioning, backup controller setup, or - The work requires platform database provisioning, backup controller setup, or
shared storage changes. shared storage changes.
- The work is application source-code behavior rather than release wiring. - The work is application source-code behavior rather than release wiring.
- The work is Forgejo production migration design rather than current Gitea - The work is forge runtime, registry retention, runner substrate, or Forgejo
operation. production migration design rather than S5 app release operation.
- The work requires secret custody, credential generation, or token storage - The work requires secret custody, credential generation, or token storage
outside approved operator paths. outside approved operator paths.
@@ -132,14 +131,12 @@ lessons into reusable S5 app release patterns.
## Current Implementation Surface ## Current Implementation Surface
- Gitea is deployed and operational as the current forge. Its S5 Helm values - Gitea is deployed and operational as the current forge. Its deploy-capable
live here, and registry settings are layered through Helm/SOPS/manifests still live here during the `railiance-forge` extraction.
`helm/gitea-registry-values.yaml`. - The Gitea container and Python package registry paths are verified. Canonical
- The Gitea container registry path is verified and documented. Package blobs registry operating docs now live in `railiance-forge`; app-side files here are
currently land on the Gitea shared PVC, so storage growth and backup/retention compatibility pointers.
posture remain important follow-up concerns. - The `issue-core` migration is still blocked on publishing `issue-core==0.2.0`
- 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 with package credentials in the `issue-core` repo and refreshing the
`vergabe-teilnahme` lock in its source repo. `vergabe-teilnahme` lock in its source repo.
- `vergabe-teilnahme` is represented as a local Helm chart plus values, - `vergabe-teilnahme` is represented as a local Helm chart plus values,
@@ -156,11 +153,10 @@ lessons into reusable S5 app release patterns.
## Known Gaps And Opportunities ## Known Gaps And Opportunities
- `docs/vergabe-teilnahme.md` still references the old local `issue-core` - Deploy-capable Gitea Helm/SOPS/manifests still need to move to
Docker build-context path in the image promotion section. It needs to be `railiance-forge` after review.
updated after the package registry handoff is fully closed. - S5 app docs should continue shedding forge-runtime details and linking to
- Gitea package blob storage is operational but not yet tied to an explicit forge-owned operating contracts.
retention, capacity, and restore posture.
- The first-app lessons from `vergabe-teilnahme` are documented, but there is - The first-app lessons from `vergabe-teilnahme` are documented, but there is
no reusable "new S5 app release checklist" yet. no reusable "new S5 app release checklist" yet.
- The manifest dry-run workflow assumes access to a representative cluster and - The manifest dry-run workflow assumes access to a representative cluster and
@@ -208,7 +204,10 @@ from that file.
- `railiance-platform`: shared CNPG clusters, backup primitives, object storage, - `railiance-platform`: shared CNPG clusters, backup primitives, object storage,
and other platform services consumed by S5 apps. and other platform services consumed by S5 apps.
- `railiance-enablement`: CI/CD and templates used by S5 releases. - `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, - `railiance-cluster`: Kubernetes runtime, ingress controllers, cert-manager,
and cluster networking. and cluster networking.
- `vergabe-teilnahme`: source Django app, package lock, Dockerfile, and app code. - `vergabe-teilnahme`: source Django app, package lock, Dockerfile, and app code.
@@ -221,7 +220,7 @@ from that file.
```capability ```capability
type: infrastructure type: infrastructure
title: S5 application workload deployment 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. description: Deploy and operate user-facing Railiance applications as Helm releases and Kubernetes manifests, including transitional Gitea deployment files and the first Django S5 app release.
keywords: [railiance, s5, gitea, registry, helm, django, vergabe-teilnahme, workload, deployment] keywords: [railiance, s5, gitea, registry, helm, django, vergabe-teilnahme, workload, deployment]
``` ```
@@ -240,8 +239,10 @@ keywords: [operator, runbook, sops, cnpg, dry-run, smoke-test, deployment]
2. Read `INTENT.md` for the stable purpose of the S5 layer. 2. Read `INTENT.md` for the stable purpose of the S5 layer.
3. Read this file for scope and boundaries. 3. Read this file for scope and boundaries.
4. Read the active files in `workplans/`. 4. Read the active files in `workplans/`.
5. For Gitea registry work, start with `docs/gitea-container-registry.md` and 5. For Gitea registry work, start with
`docs/gitea-package-registry.md`. `/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 6. For `vergabe-teilnahme`, start with `docs/vergabe-teilnahme.md`, then inspect
`charts/vergabe-teilnahme/`, `helm/vergabe-teilnahme-values.yaml`, and `charts/vergabe-teilnahme/`, `helm/vergabe-teilnahme-values.yaml`, and
`manifests/vergabe-teilnahme-ingress.yaml`. `manifests/vergabe-teilnahme-ingress.yaml`.

79
docs/gitea-container-registry.md
View File

@@ -1,77 +1,16 @@
# Gitea Container Registry # Gitea Container Registry
## Registry Target Canonical registry operating guidance now lives in:
Use `gitea.coulomb.social` as the approved registry host. The `/v2` ingress is
live as of 2026-05-15 and returns the OCI registry authentication challenge over
HTTPS.
Registry-specific Gitea settings are carried in
`helm/gitea-registry-values.yaml`, a non-secret overlay applied after the SOPS
values file by `make gitea-deploy`. It explicitly enables packages, permits
container and PyPI uploads without an app-level size cap, clears globally
disabled repo units, and moves `ROOT_URL` to the HTTPS host.
Image names should use the Gitea owner and package path:
```bash
gitea.coulomb.social/coulomb/state-hub:<tag>
```
The State Hub handoff from `CUST-WP-0011` should publish the locally verified
`state-hub:local` image under that name.
The successful smoke-test tags were:
```bash
gitea.coulomb.social/coulomb/state-hub:6186a99
gitea.coulomb.social/coulomb/state-hub:latest
```
Digest:
```text ```text
sha256:039d29654ccb3754c6ecdbe497c6364bbd8452edcdcb7fa937dd9debf5b734ff /home/worsch/railiance-forge/docs/gitea-container-registry.md
``` ```
## Operator Smoke Test This compatibility pointer remains in `railiance-apps` while deploy-capable
Gitea Helm, SOPS, and manifest files are still migrating under
`RAILIANCE-WP-0006-T03`.
Use a Gitea personal access token with package read/write permission: Use `railiance-forge` for registry endpoints, package-token handling, smoke
evidence, storage notes, retention posture, and future Forgejo registry
```bash ownership. Use `railiance-apps` only for S5 app release values and app runbooks
docker login gitea.coulomb.social that consume already-published images.
docker tag state-hub:local gitea.coulomb.social/coulomb/state-hub:<tag>
docker push gitea.coulomb.social/coulomb/state-hub:<tag>
docker pull gitea.coulomb.social/coulomb/state-hub:<tag>
```
The `coulomb` organization packages are public by default, so the verified
cluster pull for `state-hub:6186a99` did not require an `imagePullSecret`.
For private packages, create an image pull secret in each consuming namespace:
```bash
kubectl create secret docker-registry gitea-registry \
--docker-server=gitea.coulomb.social \
--docker-username=<gitea-user> \
--docker-password=<package-token> \
--namespace=<namespace>
```
Reference it from workloads as `imagePullSecrets: [{name: gitea-registry}]`.
## Python Packages
The same Gitea package service is used for Python wheels. See
`docs/gitea-package-registry.md` for the publish/install recipe and the
`issue-core` migration notes from `RAILIANCE-WP-0004 I03`.
## Current Storage Notes
The live Gitea pod mounts `gitea-shared-storage` at `/data`; package blobs land
under `/data/packages`. On 2026-05-19 that package directory was about 798.5 MiB.
The PVC is `default/gitea-shared-storage`, 10 GiB, `local-path`, `RWO`. The live
cluster showed no Kubernetes `CronJob` backup resources across namespaces on
2026-05-19. This is acceptable for the current smoke-test images, but heavy tag
growth should wait for a platform backup/retention follow-up.

52
docs/gitea-package-registry.md
View File

@@ -1,48 +1,16 @@
# Gitea Package Registry # Gitea Package Registry
Gitea package support is enabled by `helm/gitea-registry-values.yaml`. Canonical package-registry operating guidance now lives in:
That overlay is applied after the encrypted base values by
`make gitea-deploy` and enables both container packages and Python
packages.
## Python Packages ```text
/home/worsch/railiance-forge/docs/gitea-package-registry.md
Publish Python wheels to the organization package endpoint:
```bash
python -m build
TWINE_USERNAME=<gitea-user> \
TWINE_PASSWORD=<package-token> \
python -m twine upload \
--repository-url https://gitea.coulomb.social/api/packages/coulomb/pypi \
dist/*
``` ```
Install from the simple index: This compatibility pointer remains in `railiance-apps` while deploy-capable
Gitea Helm, SOPS, and manifest files are still migrating under
`RAILIANCE-WP-0006-T03`.
```bash Use `railiance-forge` for the Gitea PyPI endpoint, package-token handling,
pip install \ publish/install recipes, retention posture, and future Forgejo package
--extra-index-url https://<gitea-user>:<package-token>@gitea.coulomb.social/api/packages/coulomb/pypi/simple/ \ ownership. Use `railiance-apps` only for S5 app release values and app runbooks
issue-core that consume already-published packages.
```
For CI, store the token as a secret and inject it into the package index
URL at build time. Do not commit tokenized index URLs.
## issue-core Migration
The portable deployment path for `vergabe-teilnahme` is:
1. Release `issue-core` from its source repo as a wheel, for example
`0.2.0`.
2. Publish the wheel to the Gitea Python package registry.
3. Change `vergabe-teilnahme/pyproject.toml` from the local path
dependency to `issue-core>=0.2,<0.3`.
4. Remove the Docker BuildKit `--build-context issue-core=...`
requirement from image-build instructions.
5. Build the image on a clean runner that has no sibling `issue-core`
checkout.
Only the registry enablement lives in `railiance-apps`; the package
release and application dependency change belong to the `issue-core` and
`vergabe-teilnahme` repos.

11
docs/vergabe-teilnahme.md
View File

@@ -68,9 +68,10 @@ make vergabe-superuser # interactive createsuperuser
## Promoting a new image tag ## Promoting a new image tag
1. Build + push from `vergabe-teilnahme` repo (see its `Dockerfile` 1. Build + push from the `vergabe-teilnahme` repo using the portable package
header for the BuildKit `--build-context` invocation — see also path: `issue-core` must resolve from the Gitea PyPI registry, not from a
`RAILIANCE-WP-0004 I03`). sibling checkout. If `issue-core==0.2.0` is not published yet, keep
`railiance-apps-WP-0004 I03` in `wait`.
2. Update `image.tag` in `helm/vergabe-teilnahme-values.yaml` to the 2. Update `image.tag` in `helm/vergabe-teilnahme-values.yaml` to the
new git SHA. new git SHA.
3. `make vergabe-deploy` — Helm rolls a new ReplicaSet with 3. `make vergabe-deploy` — Helm rolls a new ReplicaSet with
@@ -152,8 +153,8 @@ configuration belongs to `railiance-platform`).
- Workplan: `workplans/railiance-apps-WP-0002-vergabe-teilnahme-on-railiance01.md` - Workplan: `workplans/railiance-apps-WP-0002-vergabe-teilnahme-on-railiance01.md`
- Improvements backlog: `workplans/railiance-apps-WP-0004-app-deployment-improvements.md` - Improvements backlog: `workplans/railiance-apps-WP-0004-app-deployment-improvements.md`
- Shared DB cluster: `railiance-platform/docs/apps-pg.md` - Shared DB cluster: `railiance-platform/docs/apps-pg.md`
- Container registry: `docs/gitea-container-registry.md` - Container registry: `/home/worsch/railiance-forge/docs/gitea-container-registry.md`
- Python package registry: `docs/gitea-package-registry.md` - Python package registry: `/home/worsch/railiance-forge/docs/gitea-package-registry.md`
- Django deployment recipe: `docs/django-on-railiance.md` - Django deployment recipe: `docs/django-on-railiance.md`
- Operator setup: `docs/operator-setup.md` - Operator setup: `docs/operator-setup.md`
- Operator recipes: `docs/operator-recipes.md` - Operator recipes: `docs/operator-recipes.md`

22
workplans/RAILIANCE-WP-0005-s5-app-release-readiness.md
View File

@@ -4,12 +4,12 @@ type: workplan
title: "S5 app release readiness and scope alignment" title: "S5 app release readiness and scope alignment"
domain: railiance domain: railiance
repo: railiance-apps repo: railiance-apps
status: ready status: active
owner: codex owner: codex
topic_slug: railiance topic_slug: railiance
planning_priority: medium planning_priority: medium
created: "2026-06-04" created: "2026-06-04"
updated: "2026-06-04" updated: "2026-06-05"
state_hub_workstream_id: "685f1c18-33c0-400d-a2b1-e1dae0f27c3e" state_hub_workstream_id: "685f1c18-33c0-400d-a2b1-e1dae0f27c3e"
--- ---
@@ -23,6 +23,10 @@ and now owns the repeatable S5 application release surface: Gitea registry
enablement, the `vergabe-teilnahme` Helm release, operator guardrails, and enablement, the `vergabe-teilnahme` Helm release, operator guardrails, and
deployment runbooks. deployment runbooks.
The 2026-06-05 `railiance-forge` extraction moved canonical registry operating
docs and registry-retention policy into the new forge layer. This workplan now
keeps only app-release readiness items in S5.
The same review found several gaps: The same review found several gaps:
- `INTENT.md` is missing, so purpose and scope are collapsed into one document. - `INTENT.md` is missing, so purpose and scope are collapsed into one document.
@@ -66,7 +70,7 @@ of carrying all purpose language itself.
```task ```task
id: RAILIANCE-WP-0005-T02 id: RAILIANCE-WP-0005-T02
status: todo status: done
priority: high priority: high
state_hub_task_id: "f8f63edb-a7ef-4692-8b01-66402d296cbb" state_hub_task_id: "f8f63edb-a7ef-4692-8b01-66402d296cbb"
``` ```
@@ -86,6 +90,9 @@ Focus areas:
Done when the Railiance operator docs describe the portable image promotion path Done when the Railiance operator docs describe the portable image promotion path
and no active runbook tells an operator to rely on a sibling repo checkout. and no active runbook tells an operator to rely on a sibling repo checkout.
Completed on 2026-06-05 by updating `docs/vergabe-teilnahme.md` and replacing
the local registry docs with compatibility pointers to `railiance-forge`.
--- ---
## T03 - Create a reusable S5 app onboarding checklist ## T03 - Create a reusable S5 app onboarding checklist
@@ -129,7 +136,6 @@ Clarify where S5 app data durability begins and ends.
Cover at least: Cover at least:
- Gitea package blobs on the shared Gitea PVC;
- `vergabe_db` on the shared `apps-pg` CNPG cluster; - `vergabe_db` on the shared `apps-pg` CNPG cluster;
- responsibility split between S5 runbooks and `railiance-platform` backup - responsibility split between S5 runbooks and `railiance-platform` backup
controllers; controllers;
@@ -137,6 +143,8 @@ Cover at least:
beyond smoke-test usage; beyond smoke-test usage;
- how to file or link platform-layer workplans when the durability gap is not - how to file or link platform-layer workplans when the durability gap is not
local to this repo. local to this repo.
- how S5 app runbooks cite forge-owned package/blob restore evidence without
owning Gitea package backup procedures.
Done when `SCOPE.md` and app runbooks clearly separate S5 release ownership from Done when `SCOPE.md` and app runbooks clearly separate S5 release ownership from
S3 backup implementation while still giving operators an actionable restore S3 backup implementation while still giving operators an actionable restore
@@ -174,7 +182,7 @@ PR checks or still needs runner/cluster preparation.
```task ```task
id: RAILIANCE-WP-0005-T06 id: RAILIANCE-WP-0005-T06
status: todo status: done
priority: medium priority: medium
state_hub_task_id: "382ba252-0f54-45fa-8e33-e656f4472341" state_hub_task_id: "382ba252-0f54-45fa-8e33-e656f4472341"
``` ```
@@ -193,3 +201,7 @@ Include:
Done when registry growth is no longer only a note in Done when registry growth is no longer only a note in
`docs/gitea-container-registry.md`. `docs/gitea-container-registry.md`.
Completed on 2026-06-05 by moving the canonical storage and retention posture
to `/home/worsch/railiance-forge/docs/initial-operating-contracts.md`; the local
registry docs are compatibility pointers.

12
workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md
View File

@@ -123,7 +123,7 @@ indexing and no reliance on `railiance-apps` as its planning home.
```task ```task
id: RAILIANCE-WP-0006-T03 id: RAILIANCE-WP-0006-T03
status: todo status: in_progress
priority: high priority: high
state_hub_task_id: "57162f50-d1a4-4fb3-b4fa-503939b22450" state_hub_task_id: "57162f50-d1a4-4fb3-b4fa-503939b22450"
``` ```
@@ -153,6 +153,11 @@ Migration rules:
Done when `railiance-apps` no longer owns source-forge deployment config, and Done when `railiance-apps` no longer owns source-forge deployment config, and
current Gitea operation has an equivalent or better home in `railiance-forge`. current Gitea operation has an equivalent or better home in `railiance-forge`.
Progress 2026-06-05: canonical registry docs moved to `railiance-forge`, with
compatibility pointers left in `railiance-apps`. Deploy-capable Gitea
Helm/SOPS/manifests and Makefile deploy targets still remain here pending a
separate review.
--- ---
## T04 - Re-scope `railiance-apps` and `railiance-enablement` ## T04 - Re-scope `railiance-apps` and `railiance-enablement`
@@ -193,7 +198,7 @@ documents without inspecting historical workplans.
```task ```task
id: RAILIANCE-WP-0006-T05 id: RAILIANCE-WP-0006-T05
status: todo status: done
priority: high priority: high
state_hub_task_id: "a99520c3-91dc-4af0-9f9b-0f0b53137be5" state_hub_task_id: "a99520c3-91dc-4af0-9f9b-0f0b53137be5"
``` ```
@@ -214,6 +219,9 @@ Cover:
Done when package and image growth, cleanup, and release evidence are not Done when package and image growth, cleanup, and release evidence are not
implicit tribal knowledge. implicit tribal knowledge.
Completed on 2026-06-05 in
`/home/worsch/railiance-forge/docs/initial-operating-contracts.md`.
--- ---
## T06 - Define CI runner, Actions, and GitOps ownership ## T06 - Define CI runner, Actions, and GitOps ownership