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.