Configuring External Docker Registries

When working with Docker, users deal with images which are executable files that contain everything needed to run an application, including the app's source code, libraries, etc. These images are stored in specialized repositories known as registries, which can be either private or public.

The most well-known public registry is Docker Hub, where you can find many official images like Nginx, PostgreSQL, Alpine, Ubuntu, Node, and MongoDB. Users can register on Docker Hub and store their images, with access to three private repositories and one public repository by default. Docker Hub is the default registry used by Docker to pull images.

This guide will cover changing Docker's default registry to another one.

Using External Docker Registries

A simple way to use external registries is to leverage third-party registries offered by companies like Google and Amazon. Below is a list of public registries you can use:

Using unknown external Docker registries may pose security risks, so proceed with caution.

Follow the steps below to switch the default Docker Hub registry to another one.

Linux Configuration

Open the daemon.json file using any text editor. If Docker is installed normally (not in rootless mode), the file is located in /etc/docker. If the file doesn’t exist, the command will create it:

nano /etc/docker/daemon.json

For Docker in rootless mode, the file is located at ~/.config/docker in the user's home directory. Again, the command will create the file if it doesn't exist:

nano ~/.config/docker/daemon.json

Add the following parameter to set a new default registry (https://mirror.gcr.io in this example):

{
  "registry-mirrors": ["https://mirror.gcr.io"]
}

Save and exit the file.

Restart the Docker service to apply the changes:

systemctl reload docker

Now, when you pull an image, Docker will use the newly specified registry. For example, pull the Alpine image from Google's registry:

docker pull mirror.gcr.io/alpine

You can also specify a tag. For instance, pull Nginx version 1.25.2:

docker pull mirror.gcr.io/nginx:1.25.2

Windows Configuration (Docker Desktop)

Open the daemon.json file located at:

C:\Users\<your_username>\.docker\daemon.json

Add the registry-mirrors parameter:

{
  "registry-mirrors": ["https://mirror.gcr.io"]
}

Save the file, then restart Docker. Right-click the Docker icon in the system tray and select "Restart."

Alternatively, you can configure the registry via Docker Desktop’s UI. Go to the Docker Engine section and add:

{
  "registry-mirrors": ["https://mirror.gcr.io"]
}

Click Apply & Restart to save the changes and restart Docker.

After restarting, Docker will use the new registry for image pulls. For example, download a curl image:

docker pull mirror.gcr.io/curlimages/curl

To pull a specific version, specify the tag. For example:

docker pull mirror.gcr.io/node:21-alpine

Using Nexus as a Docker Registry

You can also use Nexus to manage Docker images. Nexus supports proxy repositories, which cache images pulled from external registries like Docker Hub. This allows Nexus to act as a caching proxy repository for Docker images, which can be useful if external registries are unavailable.

Setting up a Proxy Repository in Nexus

1. Log in to Nexus using an administrator or a user with repository creation rights.

2. Go to Server Administration and Configuration and navigate to Repositories. Click Create repository and choose the docker (proxy) type.

3. Fill out the necessary fields:

• Name: Give the repository a unique name.

• Online: Ensure this checkbox is checked, allowing the repository to accept incoming requests.

4. If Nexus is behind a proxy server (such as Nginx), you won’t need to use ports for authentication. If no proxy is used, assign a unique port for HTTP or HTTPS.

• Allow anonymous docker pull: If checked, you won’t need to authenticate using docker login. If not checked, you’ll need to log in before pulling images.

• Remote storage: Specify the URL of the external registry (e.g., https://registry-1.docker.io for Docker Hub).

After the repository is created, log in to the Nexus registry (if authentication is required) using:

docker login <nexus_registry_address>

To pull an image, use the following format:

docker pull <nexus_registry_address>/image_name:tag

For example, to pull a Python image with tag 3.8.19-alpine:

docker pull nexus-repo.com/python:3.8.19-alpine

Avoid using the latest tag for security reasons, as it may contain bugs or vulnerabilities.

Conclusion

This article reviewed several methods for pulling and storing Docker images. Using third-party Docker registries can be helpful when the default registry is unavailable. If you don’t trust external registries, you can always set up your own private or public registry.