Registry: Zot

More information

Overview

Zot is a lightweight, OCI-native container registry serving as the central image repository for this homelab. It provides a performant, self-hosted alternative to Docker Hub with built-in authentication, deduplication, and garbage collection.

Architecture Integration

The registry operates within the NUC homelab infrastructure:

• Network Access: External requests to registry.pynezz.dev hit the VPS Caddy, which proxies through WireGuard tunnel (10.100.100.0/24) to the NUC's internal Caddy on port 3333
• Internal Routing: NUC Caddy routes /registry/* paths to the Zot container at 10.10.10.3:3000
• Container Runtime: Managed via Podman with systemd integration for automatic restarts
• Storage: Persistent data stored in ./data directory with filesystem deduplication enabled

Directory Structure

zot/
├── data/              # Registry blobs and metadata
│   ├── _blobs/       # Deduplicated image layers
│   └── _uploads/     # Temporary upload staging
└── zot-config.json   # Main configuration

Configuration Highlights

Key settings in zot-config.json:

• Storage: Deduplicated filesystem backend with garbage collection
• Authentication: htpasswd-based auth (credentials in config)
• Network: Listens on 0.0.0.0:3000 inside container
• Extensions: Search, scrub (integrity checks), and metrics enabled
• Performance: Caching enabled for metadata and converted manifests

Usage

Push images:

podman tag localhost/myapp:latest pkg.pynezz.dev/myapp:latest
podman push pkg.pynezz.dev/myapp:latest

Pull images:

podman pull pkg.pynezz.dev/myapp:latest

Login:

podman login pkg.pynezz.dev

Maintenance

• Storage location: ./data should be backed up regularly
• Garbage collection: Runs automatically based on retention policy
• Monitoring: Metrics available at :3000/metrics for Prometheus scraping
• Logs: Check with podman logs zot or journald if systemd-managed

Security Considerations

• Auth required for all operations (read/write)
• TLS terminated at VPS Caddy with Let's Encrypt certificates
• Internal communication over WireGuard encrypted tunnel
• Registry isolated in podman network, not exposed to home LAN directly

Performance Notes

Deduplication significantly reduces storage overhead when pushing similar images. The NUC's single-core CPU handles typical homelab registry traffic efficiently, though concurrent large pushes may experience throttling due to the 512MB VPS relay point.

More information

directory structure

Zot
|--data
L--zot-config.json

zot-config

´´´