Mirror - Podman Registry Mirror

Overview

The mirror command manages local registry mirrors using Podman Quadlet containers. Mirrors cache container images locally for faster pulls.

Key Concept: Transparent caching - Podman is auto-configured to use mirrors. Pulls go through the local cache; cache misses fetch from upstream.

Quick Reference

Installation

Common Registries

# GitHub Container Registry
ujust mirror install ghcr.io

# Docker Hub
ujust mirror install docker.io

# Quay.io
ujust mirror install quay.io

# NVIDIA NGC
ujust mirror install nvcr.io

With Authentication

# Private registry with auth
ujust mirror install registry.company.com 5000 user:password

Custom Port

# Custom port
ujust mirror install docker.io 5001

Port Allocation

Each registry gets a unique port:

Mirror Lifecycle

Enable/Disable

# Stop without removing
ujust mirror disable ghcr.io

# Start again
ujust mirror enable ghcr.io

View Logs

ujust mirror logs ghcr.io
ujust mirror logs docker.io 100

Check Status

# Single mirror
ujust mirror status ghcr.io

# List all
ujust mirror list

Podman Configuration

Mirrors auto-configure Podman registries.conf. After install:

# Podman transparently uses mirror
podman pull ghcr.io/org/image:tag
# Actually pulls from localhost:5000 (cached)

Cache Storage

Common Workflows

Setup for Development

# Install mirrors for common registries
ujust mirror install ghcr.io
ujust mirror install docker.io

# Verify
ujust mirror list

# Now pulls are cached
podman pull ghcr.io/org/image:tag  # First: slow (cache miss)
podman pull ghcr.io/org/image:tag  # Second: fast (cache hit)

CI/CD Optimization

# For GitHub runners
ujust mirror install ghcr.io

# Runners use cached images
# Significantly faster for repeated pulls

Private Registry

# With authentication
ujust mirror install registry.mycompany.com 5010 myuser:mypassword

# Verify
ujust mirror status registry.mycompany.com

Remove Mirror

# Remove but keep cache
ujust mirror remove ghcr.io

# Remove with cache cleanup
ujust mirror remove ghcr.io yes

How It Works

1. Install: Creates Quadlet container running registry:2 in mirror mode
2. Configure: Updates Podman registries.conf to use mirror
3. Pull: Podman checks mirror first
4. Cache hit: Serves from local cache
5. Cache miss: Fetches from upstream, caches for next time

Bandwidth Savings

Mirrors are especially useful for:

• Large images (AI/ML containers)

• Frequent rebuilds

• Multiple developers

• CI/CD pipelines

Troubleshooting

Mirror Not Working

Check:

ujust mirror status ghcr.io
ujust mirror logs ghcr.io

Verify Podman config:

cat ~/.config/containers/registries.conf.d/ghcr.io-mirror.conf

Port Conflict

Symptom: "Address already in use"

Fix:

# Use different port
ujust mirror remove ghcr.io
ujust mirror install ghcr.io 5100

Authentication Fails

Symptom: 401 errors in logs

Fix:

# Reinstall with correct credentials
ujust mirror remove registry.company.com
ujust mirror install registry.company.com 5000 correct:password

Cache Too Large

Check:

du -sh ~/.local/share/containers/mirror/

Fix:

# Remove and reinstall (clears cache)
ujust mirror remove ghcr.io yes
ujust mirror install ghcr.io

Integration with Runners

GitHub runners automatically use mirrors if configured:

# 1. Install mirror
ujust mirror install ghcr.io

# 2. Install runners
ujust runners install [https://github.com/org/repo](https://github.com/org/repo) 1

# Runners pull through mirror automatically

Cross-References

• Related Skills: runners (uses mirrors), pod (image building)

• Registry docs: https://docs.docker.com/registry/

When to Use This Skill

Use when the user asks about:

• "registry mirror", "cache container images"

• "faster pulls", "slow container downloads"

• "mirror ghcr", "mirror docker hub"

• "CI optimization", "build faster"