Zot Registry

Deploy and Host Zot Registry on Sealos

Zot Registry is an OCI-native container image registry for storing and distributing container artifacts. This template deploys Zot v2.1.14 on Sealos Cloud with built-in basic authentication and two storage backends: local filesystem or S3-compatible object storage.

About Hosting Zot Registry

Zot provides a lightweight OCI registry implementation with a web UI and registry APIs, making it suitable for private image hosting, edge distribution, and internal CI/CD artifact workflows. It supports standard Docker/OCI push and pull operations, while keeping operational complexity low.

This Sealos template supports two runtime profiles. In filesystem mode, Zot runs as a StatefulSet with persistent storage for registry data. In objectstorage mode, Zot runs as a Deployment backed by a Sealos ObjectStorage bucket, while still exposing the same public HTTPS endpoint and /v2/ API behavior.

The deployment enables basic auth and access-control policies by default, configures health probes (/livez, /readyz, /startupz), and publishes the service through Sealos-managed ingress with TLS.

Common Use Cases

• Private Team Registry: Host internal base images and application images for development and production pipelines.
• CI/CD Artifact Distribution: Push build outputs from CI jobs and pull them in deployment stages.
• Edge and Homelab Registry: Run a lightweight OCI registry for distributed or resource-constrained environments.
• Air-Gapped or Controlled Environments: Mirror and serve approved images from a controlled registry endpoint.
• OCI Artifact Hub: Store not only images but also OCI-compatible artifacts for platform tooling.

Dependencies for Zot Registry Hosting

The Sealos template includes all required dependencies for Zot runtime:

• Zot core service (ghcr.io/project-zot/zot:v2.1.14)
• Service + Ingress with HTTPS exposure
• Built-in basic authentication and repository access-control policy
• Optional Sealos ObjectStorage bucket (when zot_storage_backend=objectstorage)
• Persistent volume claim (when zot_storage_backend=filesystem)

Deployment Dependencies

• Zot Official Website - Project overview and docs entry
• Zot GitHub Repository - Source code and releases
• Zot Examples - Reference configuration files
• Sealos Documentation - Platform usage and operations

Implementation Details

Architecture Components:

This template deploys the following resources:

• Zot Workload:
  • StatefulSet in filesystem mode
  • Deployment in objectstorage mode
• Service: Exposes port 5000 for Zot API and UI
• Ingress: Public HTTPS endpoint with Sealos-managed TLS
• ObjectStorageBucket (optional): Created only in object storage mode
• ConfigMap (object storage mode): Stores Zot config and htpasswd content

Configuration:

• Default generated values:
  • app_name, app_host
• Runtime storage mode:
  • filesystem: persistent local registry data (1Gi PVC)
  • objectstorage: S3-compatible backend with Sealos ObjectStorage credentials
• Authentication:
  • Basic auth is enabled by default
  • Admin policy grants read/create/update/delete to configured admin user
• Public entrypoint:
  • https://<app_host>.<SEALOS_CLOUD_DOMAIN>
• API endpoint:
  • https://<app_host>.<SEALOS_CLOUD_DOMAIN>/v2/

License Information:

Zot is licensed under the Apache License 2.0.

Why Deploy Zot Registry on Sealos?

Sealos is an AI-assisted Cloud Operating System built on Kubernetes, designed to simplify app delivery and operations. By deploying Zot on Sealos, you get:

• One-Click Deployment: Launch a production-ready private registry without writing Kubernetes manifests.
• Kubernetes-Native Runtime: Use proven primitives (Service, Ingress, StatefulSet/Deployment) with managed networking.
• Flexible Storage Choices: Choose persistent local storage or S3-compatible object storage based on workload needs.
• Managed HTTPS Access: Get a public domain and TLS certificates automatically.
• Easy Day-2 Operations: Tune resources and behavior from Canvas via AI dialog and resource cards.
• Pay-as-You-Go Efficiency: Start small and scale resource usage according to actual traffic.

Deploy Zot on Sealos and focus on shipping artifacts instead of managing infrastructure.

Deployment Guide

1. Open the Zot template and click Deploy Now.
2. Configure parameters in the popup dialog:
   • zot_storage_backend: filesystem or objectstorage
   • zot_admin_user
   • If filesystem: set zot_admin_password
   • If objectstorage: set zot_admin_htpasswd_hash and optional zot_s3_region
3. Wait for deployment to complete (typically 2-3 minutes). After deployment, you will be redirected to Canvas. For later changes, describe requirements in the AI dialog or edit resources via resource cards.
4. Access Zot:
   • Web UI: https://<app_host>.<SEALOS_CLOUD_DOMAIN>/
   • Registry API: https://<app_host>.<SEALOS_CLOUD_DOMAIN>/v2/
5. Authenticate registry operations with your configured admin credentials.

Configuration

After deployment, you can configure Zot through:

• AI Dialog: Describe required changes and let AI apply updates.
• Resource Cards: Modify workload resources, ingress behavior, and storage profile.
• Registry Clients: Use Docker/Podman/Skopeo login and push/pull workflows against the generated domain.

Template Parameters

Scaling

To scale Zot resources:

1. Open your deployment in Canvas.
2. Select the Zot workload resource card (StatefulSet or Deployment).
3. Adjust CPU/Memory resources and apply changes.
4. For object storage mode, scale the Deployment replica count as needed and validate client behavior.

Troubleshooting

Common Issues

Issue: Pod restarts immediately in object storage mode

• Cause: Incompatible storage extension settings or invalid object storage configuration.
• Solution: Ensure object storage mode uses compatible search settings and valid S3 parameters from template defaults/inputs.

Issue: UNAUTHORIZED when calling /v2/

• Cause: Missing/incorrect basic auth credentials.
• Solution: Verify admin credentials and re-run registry login from your client.

Issue: Auth works in filesystem mode but not in object storage mode

• Cause: zot_admin_htpasswd_hash was provided as plain text instead of hash.
• Solution: Provide a bcrypt or SHA-crypt htpasswd hash (for example, generated by htpasswd -nB <user>).

Issue: Push fails for large layers

• Cause: Client-side limits or workload resource constraints.
• Solution: Increase workload resources in Canvas and retry push.

Getting Help

• Zot Documentation
• Zot GitHub Issues
• Sealos Documentation
• Sealos Discord

Additional Resources

• Zot Configuration Examples
• OCI Distribution Specification
• Skopeo Documentation

License

This Sealos template follows the templates repository license policy. Zot itself is licensed under the Apache License 2.0.