api-company/docs/registry.md

Container Registry: registry.leeworks.dev

Decision Date: 2026-05-24
Status: Planned (Phase 0 prerequisite)

---

Decision: Use Gitea's Built-in Container Registry

We will use Gitea's built-in container registry (OCI-compatible, enabled via GITEA_CONTAINER_REGISTRY) rather than deploying a separate distribution/distribution instance.

Rationale

1. No new infra — Gitea is already deployed; enabling the container registry is a config flag, not a new deployment.
2. Integrated auth — API keys, org-scoped tokens, and CI secrets work natively with the Gitea registry.
3. Simpler CI — Gitea Actions workflows can use ${{ secrets.GITEA_TOKEN }} to push to gitea.leeworks.dev/leeworks-agents/<image>.
4. OCI compliance — Gitea's container registry is OCI v1 compliant, compatible with Docker, Podman, and Kubernetes image pulls.

---

Registry Hostname

registry.leeworks.dev

This will be a reverse proxy/ingress alias for gitea.leeworks.dev (Gitea's container registry endpoint).

Alternatively, Docker clients can use the Gitea hostname directly:

gitea.leeworks.dev/leeworks-agents/<image>:<tag>

If a separate hostname is preferred by the operator, configure an Nginx ingress to proxy registry.leeworks.dev → Gitea's container registry port.

---

Image Naming Convention

registry.leeworks.dev/leeworks-agents/<repo-name>:<tag>

API	Image
ZIP Enrichment	registry.leeworks.dev/leeworks-agents/zip-enrichment:latest
Holidays	registry.leeworks.dev/leeworks-agents/holidays:latest
Air Quality	registry.leeworks.dev/leeworks-agents/air-quality:latest
Docs Site	registry.leeworks.dev/leeworks-agents/docs-site:latest

Tags should also include the git SHA for traceability: :<sha> in addition to :latest.

---

Authentication

Pushing from CI (Gitea Actions)

- name: Log in to registry
  run: |
    echo "${{ secrets.GITEA_TOKEN }}" | docker login registry.leeworks.dev \
      -u ${{ gitea.actor }} --password-stdin

- name: Build and push
  run: |
    docker build -t registry.leeworks.dev/leeworks-agents/${{ gitea.repository_name }}:${{ gitea.sha }} .
    docker push registry.leeworks.dev/leeworks-agents/${{ gitea.repository_name }}:${{ gitea.sha }}
    docker tag registry.leeworks.dev/leeworks-agents/${{ gitea.repository_name }}:${{ gitea.sha }} \
               registry.leeworks.dev/leeworks-agents/${{ gitea.repository_name }}:latest
    docker push registry.leeworks.dev/leeworks-agents/${{ gitea.repository_name }}:latest

Pulling from Kubernetes

Create an image pull secret in each namespace:

kubectl create secret docker-registry gitea-registry \
  --docker-server=registry.leeworks.dev \
  --docker-username=<gitea-user> \
  --docker-password=<gitea-token> \
  --docker-email=ci@leeworks.dev \
  -n <namespace>

Reference in pod spec:

spec:
  imagePullSecrets:
    - name: gitea-registry

---

Enabling Gitea Container Registry

If not already enabled, the Gitea administrator needs to ensure:

1. In app.ini (or Helm values), container registry is enabled:

   [packages]
   ENABLED = true
   

2. The Gitea service is accessible on port 443 at gitea.leeworks.dev.
3. If using registry.leeworks.dev as an alias, configure an Nginx Ingress:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: registry-ingress
     namespace: gitea
     annotations:
       cert-manager.io/cluster-issuer: letsencrypt-prod
       nginx.ingress.kubernetes.io/proxy-body-size: "0"
       nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
       nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
   spec:
     ingressClassName: nginx
     tls:
       - hosts:
           - registry.leeworks.dev
         secretName: registry-tls
     rules:
       - host: registry.leeworks.dev
         http:
           paths:
             - path: /
               pathType: Prefix
               backend:
                 service:
                   name: gitea-http
                   port:
                     number: 3000
   

---

Verification

# Test login
docker login registry.leeworks.dev -u <user> -p <token>

# Test push
docker pull alpine:latest
docker tag alpine:latest registry.leeworks.dev/leeworks-agents/test:latest
docker push registry.leeworks.dev/leeworks-agents/test:latest

# Test pull from cluster
kubectl run test-pull --image=registry.leeworks.dev/leeworks-agents/test:latest \
  --image-pull-policy=Always --rm -it --restart=Never -- echo "Registry works"

---

Phase 4 Reference

All API repos should update their ROADMAP.md §Phase 4 to reference:

registry.leeworks.dev/leeworks-agents/<repo>:<tag>

as the image target for CI pushes and Flux HelmRelease image references.