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
boundaries stop.
Last reviewed: 2026-06-04
Last reviewed: 2026-06-05
---
## 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`.
Kubernetes workload manifests, transitional Gitea release configuration, and
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;
- 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.
- consume the current Gitea/registry surface through the emerging
`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
lessons into reusable S5 app release patterns.
@@ -55,15 +55,16 @@ lessons into reusable S5 app release patterns.
## 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`;
- 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.
- 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`;
@@ -78,8 +79,6 @@ lessons into reusable S5 app release patterns.
- 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`.
@@ -108,7 +107,7 @@ lessons into reusable S5 app release patterns.
## Relevant When
- 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.
- Adding another user-facing S5 application release.
- 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
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 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.
@@ -132,14 +131,12 @@ lessons into reusable S5 app release patterns.
## 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`
- Gitea is deployed and operational as the current forge. Its deploy-capable
Helm/SOPS/manifests still live here during the `railiance-forge` extraction.
- 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,
@@ -156,11 +153,10 @@ lessons into reusable S5 app release patterns.
## 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.
- Deploy-capable Gitea Helm/SOPS/manifests still need to move to
`railiance-forge` after review.
- S5 app docs should continue shedding forge-runtime details and linking 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
@@ -208,7 +204,10 @@ from that file.
- `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-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.
@@ -221,7 +220,7 @@ from that file.
```capability
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.
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]
```
@@ -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.
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`.
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`.

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

@@ -1,77 +1,16 @@
# Gitea Container Registry
## Registry Target
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:
Canonical registry operating guidance now lives in:
```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:
```bash
docker login gitea.coulomb.social
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.
Use `railiance-forge` for registry endpoints, package-token handling, smoke
evidence, storage notes, retention posture, and future Forgejo registry
ownership. Use `railiance-apps` only for S5 app release values and app runbooks
that consume already-published images.

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

@@ -1,48 +1,16 @@
# Gitea Package Registry
Gitea package support is enabled by `helm/gitea-registry-values.yaml`.
That overlay is applied after the encrypted base values by
`make gitea-deploy` and enables both container packages and Python
packages.
Canonical package-registry operating guidance now lives in:
## Python Packages
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/*
```text
/home/worsch/railiance-forge/docs/gitea-package-registry.md
```
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
pip install \
--extra-index-url https://<gitea-user>:<package-token>@gitea.coulomb.social/api/packages/coulomb/pypi/simple/ \
issue-core
```
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.
Use `railiance-forge` for the Gitea PyPI endpoint, package-token handling,
publish/install recipes, retention posture, and future Forgejo package
ownership. Use `railiance-apps` only for S5 app release values and app runbooks
that consume already-published packages.

11
docs/vergabe-teilnahme.md
View File

@@ -68,9 +68,10 @@ make vergabe-superuser # interactive createsuperuser
## Promoting a new image tag
1. Build + push from `vergabe-teilnahme` repo (see its `Dockerfile`
header for the BuildKit `--build-context` invocation — see also
`RAILIANCE-WP-0004 I03`).
1. Build + push from the `vergabe-teilnahme` repo using the portable package
path: `issue-core` must resolve from the Gitea PyPI registry, not from a
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
new git SHA.
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`
- Improvements backlog: `workplans/railiance-apps-WP-0004-app-deployment-improvements.md`
- Shared DB cluster: `railiance-platform/docs/apps-pg.md`
- Container registry: `docs/gitea-container-registry.md`
- Python package registry: `docs/gitea-package-registry.md`
- Container registry: `/home/worsch/railiance-forge/docs/gitea-container-registry.md`
- Python package registry: `/home/worsch/railiance-forge/docs/gitea-package-registry.md`
- Django deployment recipe: `docs/django-on-railiance.md`
- Operator setup: `docs/operator-setup.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"
domain: railiance
repo: railiance-apps
status: ready
status: active
owner: codex
topic_slug: railiance
planning_priority: medium
created: "2026-06-04"
updated: "2026-06-04"
updated: "2026-06-05"
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
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:
- `INTENT.md` is missing, so purpose and scope are collapsed into one document.
@@ -66,7 +70,7 @@ of carrying all purpose language itself.
```task
id: RAILIANCE-WP-0005-T02
status: todo
status: done
priority: high
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
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
@@ -129,7 +136,6 @@ Clarify where S5 app data durability begins and ends.
Cover at least:
- Gitea package blobs on the shared Gitea PVC;
- `vergabe_db` on the shared `apps-pg` CNPG cluster;
- responsibility split between S5 runbooks and `railiance-platform` backup
controllers;
@@ -137,6 +143,8 @@ Cover at least:
beyond smoke-test usage;
- how to file or link platform-layer workplans when the durability gap is not
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
S3 backup implementation while still giving operators an actionable restore
@@ -174,7 +182,7 @@ PR checks or still needs runner/cluster preparation.
```task
id: RAILIANCE-WP-0005-T06
status: todo
status: done
priority: medium
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
`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
id: RAILIANCE-WP-0006-T03
status: todo
status: in_progress
priority: high
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
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`
@@ -193,7 +198,7 @@ documents without inspecting historical workplans.
```task
id: RAILIANCE-WP-0006-T05
status: todo
status: done
priority: high
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
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