railiance-forge/docs/gitea-container-registry.md

Gitea Container Registry

This is the canonical Railiance operating note for the current Gitea container registry. Compatibility pointers remain in railiance-apps; deploy-capable Gitea Helm and manifest files now live in this repo.

Registry Target

Use gitea.coulomb.social as the approved forge and registry host. The public ingress serves the Gitea web route at https://gitea.coulomb.social/, the OCI registry route at /v2, and the Python package route at /api/packages. The /v2 route returns the OCI registry authentication challenge over HTTPS. Do not use raw node IP HTTP ports for web or registry traffic; the Gitea HTTP Service is internal-only and the public standard is the HTTPS host.

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 keeps ROOT_URL on the HTTPS host.

Image names should use the Gitea owner and package path:

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:

gitea.coulomb.social/coulomb/state-hub:6186a99
gitea.coulomb.social/coulomb/state-hub:latest

Digest:

sha256:039d29654ccb3754c6ecdbe497c6364bbd8452edcdcb7fa937dd9debf5b734ff

Operator Smoke Test

Use a Gitea personal access token with package read/write permission:

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:

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 the forge/platform backup and retention follow-up in docs/backup-restore-secret-handoff.md.