# Registry: Zot

[More information](https://zotregistry.dev/v2.1.8/)

## 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

```plaintext
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:**

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

**Pull images:**

```bash
podman pull pkg.pynezz.dev/myapp:latest
```

**Login:**

```bash
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](https://zotregistry.dev/v2.1.8/)

## directory structure

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

## zot-config

```json
´´´
```