Vetrix Docs

Registry Volume — Operator Setup

The package + container registry subsystem stores OCI manifests, blob bytes, and package archives (/v2, /npm, /pypi, /go) on disk under a single configured root. This doc describes the operator-side setup that the API expects.

Layout

{VETRIX_BLOB_DIR}/
├── sha256/
│   ├── ab/
│   │   └── abcdef0123…/        # content-addressed blob files
│   └── …
├── uploads/
│   └── <upload-uuid>           # in-flight chunked uploads
└── ...

The on-disk layout is content-addressed; the registry handler resolves manifests + blobs through the database (internal/registry) and reads bytes back via the BlobStore rooted at VETRIX_BLOB_DIR. Operators should treat the directory as opaque — files are written, read, and garbage-collected exclusively by the server.

Mount + permissions

  • The volume root MUST be on a filesystem that supports O_NOFOLLOW and standard POSIX permissions.
  • Owner of the root: the same UID/GID Vetrix runs under (typically vetrix:vetrix).
  • Mode: 0750 on the root (drwxr-x---). Group-readable so backup tooling under the same group can list files; other-not-readable so tenants on a shared host don't accidentally inventory each other.
  • Subdirectories created at runtime use 0750.
  • Files created at runtime use 0640.
sudo mkdir -p /var/lib/vetrix/blobs
sudo chown vetrix:vetrix /var/lib/vetrix/blobs
sudo chmod 0750 /var/lib/vetrix/blobs

Then point the application at it:

VETRIX_BLOB_DIR=/var/lib/vetrix/blobs

VETRIX_BLOB_DIR overrides the storage.blob_dir TOML key when both are set — the env var wins. The TOML default (data/blobs) is a best-effort fallback for development; production deployments should set the env var explicitly.

Default deployments

The default compose + k8s artefacts shipped with Vetrix wire this for you, so a fresh docker compose up (or kubectl apply -k deployments/kubernetes) produces a working registry surface without any extra operator steps. The wiring mirrors the Downloads + Plans patterns 1:1: a default VETRIX_BLOB_DIR=/data/blobs on the existing vetrix-data named volume, an init-data-dirs initContainer extension that pre-creates /data/blobs mode 0750 against the bound PVC, and a Dockerfile pre-create at image-build time.

The VETRIX_BLOB_DIR env var only needs customisation for bespoke storage layouts — for example, a separate object-storage-backed volume mounted at a non-default path, or a multi-tenant deployment where the blob tree sits on dedicated tier-1 storage.

Disabling the registry explicitly

The boot path enforces a fail-stop on the registry env vars, mirroring the Downloads + Plans contract. The binary refuses to start when VETRIX_BLOB_DIR is unset AND VETRIX_REGISTRY_DISABLED is not set to 1.

The exact contract:

VETRIX_BLOB_DIR VETRIX_REGISTRY_DISABLED Result
set (any) Registry enabled; OCI + package routes mounted; GC scheduler started.
unset 1 Registry explicitly disabled; routes return 404; GC scheduler does not start; single WARN at boot.
unset unset (or any non-1) Boot fails with a level=ERROR line; process exits 1.

To intentionally run a deployment without the registry (for example a Vetrix host that delegates container hosting to an external registry), set:

VETRIX_REGISTRY_DISABLED=1

The routes affected when the registry is disabled are the entire OCI v2 surface plus the package-registry surfaces:

  • GET /v2/
  • GET /v2/<name>/tags/list
  • GET|HEAD /v2/<name>/manifests/<ref>
  • PUT|DELETE /v2/<name>/manifests/<ref>
  • GET|HEAD|DELETE /v2/<name>/blobs/<digest>
  • POST|GET|PATCH|PUT /v2/<name>/blobs/uploads/...
  • the /npm, /pypi, /go package registry surfaces (see the npm, PyPI, and Go registry guides in user-docs)

The registry.enabled runtime admin setting (default true) is a soft gate layered on top of the boot-time wiring. With VETRIX_BLOB_DIR unset / VETRIX_REGISTRY_DISABLED=1 the routes are not mounted in the first place; flipping registry.enabled to false while the routes are mounted disables push/pull at the authorisation layer without unwinding the wiring.

Backup considerations

  • The blob tree is included in the standard Vetrix backup target (see the backup guide in admin-docs).
  • Content-addressed paths mean restoring an older snapshot can leave the database referencing blobs that no longer exist on disk; the registry GC scheduler tolerates this by treating absent blobs as eligible-for-removal. Restore the database and the blob tree from the same backup snapshot to keep them consistent.
  • Subdirectory modes are preserved; restore as the same UID/GID.

Migration notes

This is a greenfield directory tree — the layout is content-addressed under SHA-256 and there is no legacy on-disk format to migrate from. Existing deployments that previously relied on storage.blob_dir (TOML) keep working because VETRIX_BLOB_DIR, when set, simply overrides the TOML key.