In my ongoing homelab journey, my Unraid NAS has become the absolute backbone of my storage and utility services. As my setup evolved, I quickly found myself needing a local Docker registry to push and pull my own custom images without relying on Docker Hub's rate limits or paying for cloud storage.

In order to get the Registry up and running I installed the "DockerRegistry" application from the unraid community store. However, one thing that the app is missing is instructions on how to setup authentication.

Step 1: Generating the Secrets

The official registry:2 image relies on good old-fashioned htpasswd for basic authentication. Instead of messing with internal container configuration files, the cleanest way to handle this on Unraid is by passing the auth file through a volume mount.

First, I needed to generate the actual password file. I SSH'd into my Unraid server (you can also use the built-in terminal from the web UI) and created a dedicated directory in my appdata share to hold the secret:

mkdir -p /mnt/user/appdata/registry/auth

Next, I ran the htpasswd command to generate the file and encrypt the password. Note, that I am running this inside the httpd:2 image, as unraid does not come with htpasswd. The -B flag uses bcrypt, which is highly recommended over the default MD5 encryption. When you run this, it will prompt you to type your new password twice:

docker run \
  --entrypoint htpasswd \
  httpd:2 -Bbn USERNAME PASSWORD > /mnt/user/appdata/registry/auth/htpasswd

Step 2: Setting up the Container via Unraid UI

With the credentials generated, it was time to tell the Docker container to actually use them. I went to the Docker tab in Unraid, clicked on my registry container, and selected Edit.

In order to properly configure the Registry container, we can just inject a few environment variables right from the Unraid UI. I clicked "Add another Path, Port, Variable, Label or Device" and added the following three variables:

  • Variable 1: Key: REGISTRY_AUTH | Value: htpasswd
  • Variable 2: Key: REGISTRY_AUTH_HTPASSWD_REALM | Value: RegistryRealm (You can name the realm whatever you like)
  • Variable 3: Key: REGISTRY_AUTH_HTPASSWD_PATH | Value: /auth/htpasswd (This is where the container will look for the file)

Finally, I needed to map the folder I created in Step 1 to the /auth directory inside the container. I added one more configuration item, this time as a Path:

  • Container Path: /auth
  • Host Path: /mnt/user/appdata/registry/auth
  • Access Mode: Read Only (Always a good security practice!)

After hitting Apply, Unraid gracefully stopped the container, reconfigured it with the new parameters, and spun it back up.

After the restart, I was finally able to run:

docker login myregistry.example.com

It prompted me for the username and password I created earlier, and greeted me with a satisfying Login Succeeded.

Note: Make sure your registry is secured with proper SSL certificates. You could use a reverse proxy like caddy or NPM to do this.

Closing Thoughts

Retrofitting authentication took maybe ten minutes, but it brought a lot of peace of mind.