ZOT OCI Registry

zot is a lightweight, production‑ready OCI image registry written in Go that adheres strictly to the OCI Image and Distribution specifications. It exposes a RESTful API compatible with Docker Hub and other OCI registries, enabling seamless pull/push of images while storing them in the native OCI layout on disk. The registry is designed for self‑hosting, offering a minimal dependency footprint and a focus on security and performance. Developers can integrate zot into CI/CD pipelines, micro‑service architectures, or edge deployments where a lightweight, vendor‑neutral registry is required.

Key Features & Core Capabilities

• OCI‑compliant storage – Images, manifests, and blobs are stored in the OCI directory layout (/blobs/sha256/..., /manifests/...), ensuring compatibility with any OCI‑conforming client.
• Layered caching & deduplication – zot implements content addressing; identical layers are stored once, reducing storage usage and improving upload times.
• Registry API & Webhooks – Full support for the OCI Distribution API, including tag listing, manifest retrieval, and blob upload/download. Webhook endpoints allow external services to react to events such as image pushes or deletions.
• Content Trust – Optional integration with Docker Content Trust (notary) for signed images, enhancing security in regulated environments.
• Policy & RBAC – Fine‑grained access control via policy files or external OAuth providers, enabling multi‑tenant usage in shared clusters.

Architecture & Technical Stack

• Language & Runtime – Implemented entirely in Go (1.20+), compiled to a single binary with no external dependencies, which simplifies deployment and CI/CD integration.
• Storage Backend – The default backend is a local filesystem using the OCI layout; an optional S3‑compatible object store can be configured via environment variables, making it suitable for distributed deployments.
• HTTP Server – Built on Go’s net/http with a modular router that supports middleware for authentication, logging, and metrics.
• Metrics & Observability – Exposes Prometheus metrics (/metrics) and supports OpenTelemetry traces, allowing developers to monitor registry performance in real time.
• Testing & Conformance – Continuous integration pipelines run unit tests, fuzzing, and OCI conformance checks (oci-conformance-action.yaml), ensuring that the registry remains spec‑compliant.

Deployment & Infrastructure

zot is fully container‑friendly. A minimal Docker image (project-zot/zot:latest) can be run with a single command, mounting a host directory for persistent storage. For high‑availability scenarios, developers can deploy multiple replicas behind an ingress controller or load balancer; the registry’s stateless design and external object‑store support enable horizontal scaling. Kubernetes operators (e.g., Helm charts) are available in the community, providing declarative deployment and automated lifecycle management.

Integration & Extensibility

• Plugin System – While zot itself is lightweight, it exposes hooks for custom authentication and authorization plugins via environment variables or external services.
• Webhooks & Callbacks – Post‑push, pre‑delete, and other lifecycle events can trigger arbitrary HTTP callbacks, facilitating integration with CI pipelines, security scanners, or image scanning services.
• CLI & SDK – The Go client library (zotregistry.dev/zot/v2) allows developers to programmatically interact with the registry, automating image promotion or cleanup tasks.
• Extensible Storage – By swapping the local filesystem backend with an S3 or Ceph gateway, teams can leverage existing object storage infrastructure without changing application code.

Developer Experience

zot prioritizes clear, concise documentation hosted at https://zotregistry.dev. Configuration is file‑based (config.json) with optional environment overrides, and the API follows standard OCI conventions, reducing onboarding friction. The project’s active community on GitHub, combined with a CodeQL and OpenSSF Scorecard audit, provides confidence in security and code quality. Licensing under the Apache 2.0 license allows unrestricted use, modification, and redistribution in commercial products.

Use Cases

• Edge & IoT – Deploy a lightweight registry on edge nodes to cache base images locally, reducing bandwidth and latency.
• CI/CD Pipelines – Use zot as a private cache or artifact store in continuous integration workflows, ensuring reproducible builds.
• Multi‑Tenant Environments – Run a single registry instance with fine‑grained RBAC to serve multiple teams or projects within an organization.
• Compliance & Security – Enforce signed image policies and audit trails via webhooks, meeting regulatory requirements for containerized workloads.

Advantages Over Alternatives

Developers choose zot when they need a fast, spec‑compliant registry that can be embedded into their own tooling or infrastructure without the overhead of a full