Core Concepts

The vocabulary behind everything in Dodil Registry.

Repositories

A repository is a named collection of images under your organization: <host>/<org>/<repo>. Repositories are name-keyed per org — the org name (not id) appears in the image path and in every control-plane URL.

Repositories are created implicitly by the first push. There is no create call anywhere in the API; docker push registry.dodil.io/acme/web:1.0.0 brings acme/web into existence. Each repository tracks its artifact count, pull count, creation/update time, and visibility.

Artifacts, tags, digests

An artifact is one pushed image (or OCI artifact), identified by its content digest (sha256:...). The digest is immutable — the same bytes always hash to the same digest.
A tag is a mutable, human-friendly pointer to an artifact (latest, 1.0.0). One artifact can carry many tags; retagging moves the pointer, not the bytes. Tags can be flagged immutable, after which they can’t be repointed.
Control-plane and CLI operations take a reference — either a tag or a digest — wherever they address an artifact.

Deleting an artifact (by tag or digest) removes the artifact and all its tags.

Visibility

Every repository is private by default: pulls and pushes require credentials with a registry role in the org. Setting a repository public allows anonymous pulls (pushes still require auth):


dodil registry visibility web public

The console asks for confirmation before making a repository public — treat it as a security change.

Vulnerability scanning

Every pushed artifact is scanned for CVEs at push time. The scan produces:

an overview — scan status, overall severity, total vulnerability count, and how many have a fix available — shown as the scan badge on artifact lists, and
a full report — per-CVE id, severity, affected package and version, fix version, description, and reference links.

Severity is the worst finding in the image, on the ladder Critical > High > Medium > Low > Negligible > None (plus Unknown). Read reports with dodil registry vuln or the vulnerabilities endpoint.

The two-plane architecture

Registry is HTTP-first — no gRPC, no wire adapters, no SDK. One host (registry.dodil.io) serves two planes:

Plane	Paths	Speaks to
Data plane	`/v2/...`	`docker`, `podman`, `oras`, buildkit — the standard Docker Registry v2 / OCI distribution API. Manifests, blobs, uploads.
Control plane	`/<org>/...`	The console, `dodil registry`, your scripts — REST endpoints for repo listing, artifacts, tags, vulnerability reports, visibility.

Docker clients never touch the control plane, and the control plane never moves image bytes. This is a deliberate contrast with products like Dodil Data that expose many protocol adapters: for images, the ecosystem already standardized the wire protocol, so Registry implements it directly and keeps management as plain REST.

Auth

Two credentials work on both planes:

dk_ API keys — opaque tokens issued by dodil auth apikey issue --role registry.developer --service registry, bound to a service account. Used as the password in Basic auth (docker login — username can be anything) or as a Bearer token. This is the credential for docker clients, CI, and headless scripts.
Bearer JWT — your interactive dodil auth login session token, used by the console and the CLI.

Access is org-scoped through IAM roles on the registry service (e.g. registry.developer); keys can be further scoped with --drn and expired with --ttl.