Example Docker Registry with Let's Encrypt SSL

This is a simple example of a Docker Registry with Let's Encrypt SSL. It uses Caddy as a reverse proxy and Let's Encrypt for SSL.

Caution

This repo serves as a simple example of a Docker Registry with Let's Encrypt SSL. It isn't considered production-ready. We use this repo simply for testing purposes with other applications.

Features

• 🔒 Automatic HTTPS - Let's Encrypt certificates via Caddy (zero configuration)
• 🔐 Basic Authentication - htpasswd-based user authentication
• 👥 Multi-user Support - Separate admin (read-write) and reader (read-only) accounts
• 🚀 Easy Setup - One-command deployment with Docker Compose
• 📦 Latest Registry - Uses Docker Registry v3 (OCI Distribution Spec compliant)
• 🔄 Auto-renewal - SSL certificates automatically renewed
• 📊 HTTP/3 Support - Modern protocol support out of the box

Quick Start

1. Clone and Configure

# Copy environment template
cp env.example .env

# Edit with your domain and email
nano .env

Update .env:

REGISTRY_DOMAIN=registry.example.com  # Your actual domain

2. Create User Accounts

Option A: Using the setup script (recommended)

./setup.sh

Option B: Manual setup

mkdir -p auth

# Create admin user (read-write)
docker run --rm --entrypoint htpasswd httpd:2 -Bbn admin YourPassword > auth/htpasswd

# Add reader user (read-only)
docker run --rm --entrypoint htpasswd httpd:2 -Bbn reader YourPassword >> auth/htpasswd

3. Start the Registry

docker-compose up -d

4. Verify It Works

# Check logs
docker-compose logs -f

# Test the endpoint (wait ~30 seconds for cert generation)
curl https://registry.example.com/v2/
# Should return: {} (after authentication)

5. Use Your Registry

# Login
docker login registry.example.com
# Username: admin (or reader)

# Tag and push (admin only)
docker tag ubuntu:latest registry.example.com/myapp:latest
docker push registry.example.com/myapp:latest

# Pull (both users)
docker pull registry.example.com/myapp:latest

Prerequisites

• Docker and Docker Compose installed
• Domain name with DNS A record pointing to your server
• Ports 80 and 443 open on your firewall/security group
• Public IP address (required for Let's Encrypt validation)

User Accounts

User	Access	Use Case
admin	Read-Write	Push and pull images
reader	Read-Only*	Pull images only

Usage Examples

Basic Operations

# Login to registry
docker login registry.example.com

# Pull an image from Docker Hub
docker pull alpine:latest

# Tag for your registry
docker tag alpine:latest registry.example.com/alpine:latest

# Push to your registry
docker push registry.example.com/alpine:latest

# Pull from your registry
docker pull registry.example.com/alpine:latest

Managing Multiple Accounts

Add more users to the htpasswd file:

# Add a new user
docker run --rm --entrypoint htpasswd httpd:2 -Bbn newuser password >> auth/htpasswd

# Restart registry to apply changes
docker-compose restart registry

Our Sponsors

All of our software is free and open to the world. None of this can be brought to you without the financial backing of our sponsors.

Platinum Sponsors

Silver Sponsors

Bronze Sponsors

Deimos Industries · CarePilot (Formerly DocuCare)

Infrastructure Sponsors

These companies give us free access to the tools and infrastructure we use to build, test, and ship our open source projects. Their support helps our entire community.

  

About Us

We're Dan and Jay - a two-person team with a passion for open source products. We created Server Side Up to help share what we learn.

Dan Pastori	Jay Rogers

Hire Us

Get two senior Laravel experts who deliver quality code with predictable monthly pricing. Dan and Jay have 30+ years of combined experience building scalable Laravel applications.

• 🎯 Complete Laravel expertise - Full-stack development, CI/CD, database optimization, mobile apps
• 💰 Predictable pricing - Fixed monthly subscription, no hourly billing surprises, 40%+ savings
• ⚡ Maximum productivity - 90%+ development time, no meetings, results in days not weeks
• 🛡️ Risk-free - 7-day money-back guarantee, cancel anytime

💬 Discuss Your Project →

Find us at:

• 📖 Blog - Get the latest guides and free courses on all things web/mobile development.
• 🙋 Community - Get friendly help from our community members.
• 🤵‍♂️ Get Professional Help - Get video + screen-sharing support from the core contributors.
• 💻 GitHub - Check out our other open source projects.
• 📫 Newsletter - Skip the algorithms and get quality content right to your inbox.
• 🐥 X (Twitter) - You can also follow Dan and Jay.
• ❤️ Sponsor Us - Please consider sponsoring us so we can create more helpful resources.

Our Products

If you appreciate this project, be sure to check out our other projects.

🛠️ Premium

• Self-Host Pro: Sell self-hosted software in minutes.
• Spin Pro: Production-ready Docker templates for shipping quickly.

🌍 Open Source

• serversideup/php: Supercharged PHP Docker images, based off the official PHP images.
• Spin: Docker Simplified. Deploy Anywhere. Zero Downtime. Any OS.
• Financial Freedom: Open source alternative to Mint, YNAB, and more.
• AmplitudeJS: Customize the design of any element of the HTML5 Audio Player.
• webext-bridge: Messaging in Web Extensions made easy. Batteries included.
• serversideup/ansible: Run Ansible anywhere with a lightweight and powerful Docker image.

📚 Books

• Building Browser Extensions: Build browser extensions for Firefox, Chrome, and more.
• Ultimate Guide To Building APIs & SPAs: Build web and mobile apps from the same codebase.