From c8e50e6e849c2fee12f64226529bb9324059e028 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 5 Jun 2026 12:07:26 +0200 Subject: [PATCH] Point app registry docs at railiance-forge --- SCOPE.md | 65 +++++++-------- docs/gitea-container-registry.md | 79 +++---------------- docs/gitea-package-registry.md | 52 +++--------- docs/vergabe-teilnahme.md | 11 +-- ...LIANCE-WP-0005-s5-app-release-readiness.md | 22 ++++-- ...ANCE-WP-0006-railiance-forge-extraction.md | 12 ++- 6 files changed, 85 insertions(+), 156 deletions(-) diff --git a/SCOPE.md b/SCOPE.md index 3f51ba9..32bdbca 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -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`. diff --git a/docs/gitea-container-registry.md b/docs/gitea-container-registry.md index 2269ef4..04d6457 100644 --- a/docs/gitea-container-registry.md +++ b/docs/gitea-container-registry.md @@ -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: -``` - -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: -docker push gitea.coulomb.social/coulomb/state-hub: -docker pull gitea.coulomb.social/coulomb/state-hub: -``` - -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= \ - --docker-password= \ - --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. diff --git a/docs/gitea-package-registry.md b/docs/gitea-package-registry.md index 291dfd8..d97ac49 100644 --- a/docs/gitea-package-registry.md +++ b/docs/gitea-package-registry.md @@ -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= \ -TWINE_PASSWORD= \ -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.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. diff --git a/docs/vergabe-teilnahme.md b/docs/vergabe-teilnahme.md index 3b6213b..6330b09 100644 --- a/docs/vergabe-teilnahme.md +++ b/docs/vergabe-teilnahme.md @@ -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` diff --git a/workplans/RAILIANCE-WP-0005-s5-app-release-readiness.md b/workplans/RAILIANCE-WP-0005-s5-app-release-readiness.md index dd04859..2d284dc 100644 --- a/workplans/RAILIANCE-WP-0005-s5-app-release-readiness.md +++ b/workplans/RAILIANCE-WP-0005-s5-app-release-readiness.md @@ -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. diff --git a/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md b/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md index 9cdbd2c..f41a9ea 100644 --- a/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md +++ b/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md @@ -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