Setting Up a Private Docker Registry on My Home Server

1. Install Docker on Home Server

Ensure Docker is installed and running on home server:

sudo apt update 
sudo apt install docker.io 
sudo systemctl start 
docker sudo systemctl enable docker

2. Create the docker-compose.yml File

I am creating the docker-compose file inside /opt/private-registry

cd /opt
sudo mkdir private-registry
sudo nano docker-compose.yml 

I pasted the following to the docker-compose file

services:
  registry:
    image: registry:2
    container_name: private-registry
    ports:
      - "5000:5000"
    volumes:
      # Persist registry data on the server
      - ./data:/var/lib/registry
      # Optional: SSL certificates for HTTPS
      #- ./certs:/certs
      # Optional: Authentication credentials
      - ./auth:/auth
    environment:
      # Enable TLS (if certs are provided)
      #REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
      #REGISTRY_HTTP_TLS_KEY: /certs/domain.key
      # Enable authentication (if auth is configured)
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: "Registry Realm"
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
    restart: always

Using SSL certificates for HTTPS is recommended for secure communication. Since I am using it locally in my network for testing purpose I wont be using https.

3. Setup Required Files and Folders

a. Data Directory

• Create a data directory in the same folder as docker-compose.yml to store your images:

  mkdir data

b. Authentication (Optional - I will be using authentication)

• Install htpasswd if not already installed:

  sudo apt install apache2-utils

• Create the auth directory:

  mkdir auth

• Generate a username and password file:

  htpasswd -Bc auth/htpasswd <username>

c. SSL Certificates (Optional - I won’t be using this)

• If you want to use HTTPS, create the certs directory:

  mkdir certs

• Generate self-signed certificates:

  openssl req -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key -x509 -days 365 -out certs/domain.crt

• When prompted, use your server’s IP address or domain as the "Common Name (CN)".

3. Start the Registry

Run the Docker Compose file:

docker-compose up -d

This will:

1. Start a private Docker registry on port 5000.

2. Enable optional authentication (if auth is configured).

When running docker ps it will show the as below:

4275c120ecfa   registry:2                                               "/entrypoint.sh /etc…"   22 hours ago    Up 22 hours   0.0.0.0:5000->5000/tcp, :::5000->5000/tcp                                                  private-registry

4. Push and Pull Images

a. Tag Your Image

Tag the Docker image for your private registry:

docker tag my-app <home-server-ip>:5000/my-app

b. Login to the Registry (If Authentication is Enabled)

docker login <home-server-ip>:5000

If we can successfully login then we can verify that docker registry is successfully set up

c. Push the Image

docker push <home-server-ip>:5000/my-app

d. Pull the Image

On any machine, pull the image from your private registry:

docker pull <home-server-ip>:5000/my-app