---
title: "Deploying a Password-Protected Docker Registry Mirror"
date: 2024-09-27T16:36:41.000Z
author: Z.SHINCHVEN
tags: [Docker, Registry, Security, Docker Registry Mirror]
canonical: https://atlassc.net/2024/09/28/deploying-a-password-protected-docker-registry-mirror
---
You can deploy a password-protected Docker registry mirror and authenticate clients using basic authentication or, preferably, token-based authentication. Here's how to do it, focusing on the more secure token-based approach:

## 1. Deploying the Registry with Password Authentication (Token-Based):

We'll use the official Docker Registry image and configure it with a `.htpasswd` file for user authentication.  However, this will only protect the registry itself; pushing and pulling images will leverage token-based authentication managed by the registry.

```bash
# Create a htpasswd file (replace 'username' and 'password' with your credentials)
htpasswd -B /auth/htpasswd username

# Start the registry with the authentication configuration
docker run -d \
  -p 5000:5000 \
  -v /auth:/auth \
  --name registry \
  registry:2

# Check logs to ensure it started correctly
docker logs registry
```

**Explanation:**

* `-v /auth:/auth`: Mounts a volume containing the `.htpasswd` file into the container at `/auth`.  The directory `/auth` on your host should contain the `htpasswd` file you created.
* `registry:2`:  Specifies the Docker Registry version 2.

## 2. Authenticating Clients:

Clients interact with a password-protected registry by obtaining a time-limited authentication token.  This is done automatically by the Docker client when you try to push or pull.  However, you need to login first:

```bash
docker login localhost:5000
# Enter username and password when prompted.
```

**Behind the Scenes:**

* **Login Process:** When you `docker login`, the Docker client contacts the registry's authentication endpoint (configured automatically during registry startup).  It sends the username and password (from the `docker login` command) for verification against the `.htpasswd` file.
* **Token Issuance:** If authentication is successful, the registry issues a JSON Web Token (JWT) to the client.
* **Subsequent Requests:** The Docker client includes this JWT in the `Authorization` header of all subsequent push and pull requests. The registry validates the token to authorize the operation.

## 3. Important Considerations for Production:

* **HTTPS:** In a production environment, **always** use HTTPS.  This encrypts communication between clients and the registry, protecting sensitive data like passwords and image layers.  You'll need to configure SSL certificates for your registry.  Let's Encrypt is a popular choice for free certificates.
* **Persistence:** Use a volume to store registry data persistently, so you don't lose your images if the container restarts.  Example: `-v /var/lib/registry:/var/lib/registry`
* **Authentication Backends:**  For more robust authentication and authorization, consider integrating the registry with an external authentication provider like LDAP, Active Directory, or a cloud-based identity service.  The registry's configuration supports various auth backends.
* **Authorization:** Authentication verifies *who* you are. Authorization determines *what* you can do.  You might want to explore registry authorization solutions to fine-tune access control to specific images or repositories.

**Example Docker Compose (with HTTPS and Persistence -  replace placeholders):**

```yaml
version: "3.8"
services:
  registry:
    image: registry:2
    ports:
      - "5000:5000"  # Adjust port mappings as needed
    volumes:
      - /path/to/registry-data:/var/lib/registry
      - /path/to/certs:/certs
    environment:
      REGISTRY_HTTP_TLS_CERTIFICATE: /certs/your_certificate.crt
      REGISTRY_HTTP_TLS_KEY: /certs/your_certificate.key
      REGISTRY_AUTH_HTPASSWD_REALM: "Registry Realm"
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
    volumes:
      - /path/to/auth/dir:/auth # Directory with htpasswd file
```

Remember to generate your certificates and replace the placeholder paths and filenames.  This enhanced example provides a more secure and robust setup for a production-like environment.  Always prioritize security best practices when deploying a Docker registry.