Gitea backend

The cloud-product artifact registry is a Gitea instance. Gitea provides a built-in npm-compatible packages API, which is what the Matrix install path consumes.

Topology

              443/HTTPS
hivecast.ai ─────────────► Caddy ─┬─► localhost:3198  (matrix-host gateway)
                                  │
                                  └─► (other handlers)

                  443/HTTPS
registry.hivecast.ai ────────────► Caddy ─► localhost:3000 (Gitea)

The Caddy site block for the registry is intentionally minimal:

# projects/deploy-cloud/Caddyfile.bare:92-95
registry.hivecast.ai {
  reverse_proxy localhost:3000
}

No auth gating, no rewrite rules, no header injection. Gitea owns its own authentication and authorization.

Provisioning

projects/deploy-cloud/setup-aws.sh provisions the Gitea container during initial host setup with these defaults:

# projects/deploy-cloud/setup-aws.sh:246-252
GITEA_EXTERNAL_URL=https://registry.$DOMAIN
GITEA_ADMIN_USER=hivecast-admin
GITEA_ADMIN_PASSWORD=changeme
GITEA_ADMIN_EMAIL=admin@$DOMAIN

Caution: changeme is the default in setup-aws.sh and .env.example. Production deploys MUST set GITEA_ADMIN_PASSWORD to a real value before any publish runs. The npm publish safety audit (projects/matrix-3/packages/docs/content/security/npm-publish-safety.md) calls this out as an open infrastructure concern.

After provisioning, the admin user creates an organization (open-matrix for the canonical scope) and grants tokens with push access to that org.

What Gitea provides

Feature	Lives where	Used by Matrix?
npm packages API	/api/packages/<owner>/npm/...	yes — the only consumed surface
Generic packages API	/api/packages/<owner>/generic/...	not currently
Container registry	/api/packages/<owner>/container/...	not currently
Git repository hosting	/<owner>/<repo>	not currently — Matrix uses GitHub for source
Issue tracking	/<owner>/<repo>/issues	not currently
User authentication	session/token-based	yes — for publishing

The integration is intentionally narrow: only the npm packages API is exercised by Matrix tooling. Gitea's other features are not part of the Matrix contract — they remain available, but no Matrix code depends on them.

Why Gitea, not npmjs.com

Three reasons:

1. Pre-launch deletion. npmjs.com does not allow deletion of published versions. During pre-launch development the publish path is exercised thousands of times and many versions need to be retracted or replaced. Gitea allows deletion; this matters until the public launch gate.
2. No public exposure of in-progress packages. Matrix packages depend on each other heavily. Publishing a half-completed @open-matrix/foo to public npm before the dependent @open-matrix/bar ships would publicly expose half-finished APIs.
3. Unified domain. registry.hivecast.ai is on the same domain as the product. No separate npm org provisioning is required; auth is owned by the same operator.

The npm publish safety doc covers what would have to change before publishing to public npm. The Gitea backend remains the default for pre-launch and may continue as the canonical private channel after public publish lands.

Operational shape

# Configure consumer
echo "@open-matrix:registry=https://registry.hivecast.ai/api/packages/hivecast-admin/npm/" >> ~/.npmrc

# Pull a package
npm install @open-matrix/chat

# Publish a package (publisher only)
NPM_CONFIG_REGISTRY=https://registry.hivecast.ai/api/packages/hivecast-admin/npm/ \
NPM_CONFIG__AUTH_TOKEN=<gitea-token> \
npm publish

There is no Matrix-specific CLI for the artifact registry today. Standard npm and pnpm tooling work directly.

Failure modes

Failure	Symptom	Fix
Gitea container down	npm install errors with HTTP 502	Restart Gitea container; check docker compose logs gitea.
Caddy not routing	TLS handshake completes but 404s	Verify Caddyfile.bare block; reload Caddy.
Token expired	HTTP 401 on publish	Issue new token via Gitea admin UI; rotate NPM_CONFIG__AUTH_TOKEN.
Disk full on registry host	HTTP 507 on publish	Provision storage; Gitea stores blobs under its data volume.

See also

• npm-compatible packages — the protocol the Gitea backend speaks
• Authentication — token issuance and rotation
• Caddy / TLS integration

Source: projects/deploy-cloud/Caddyfile.bare, projects/deploy-cloud/setup-aws.sh.