Setting Up A Docker Registry With HTTPS(LetsEncrypt) and Basic Authentication(htpasswd)
I’ve recently had to set up a Docker registry with HTTPS enabled and basic authentication. I was something quick, easy and preferably free, so after some reading, I decided to use the following:
- Let’s Encrypt — to server traffic over https
- Htpasswd — for simple basic authentication
- Portainer — a basic Docker web ui
- Docker-compose — one file, multiple containers
Introduction and Basic Info
A brief description of each of the above, you can skip this and go directly to the setting up section.
Let’s Encrypt
Let’s Encrypt is a free, automated, and open certificate authority (CA), run for the public’s benefit. It is a service provided by the Internet Security Research Group (ISRG).
We give people the digital certificates they need in order to enable HTTPS (SSL/TLS) for websites, for free, in the most user-friendly way we can. We do this because we want to create a more secure and privacy-respecting Web.
Htpasswd
htpasswd
is used to create and update the flat-files used to store usernames and password for basic authentication of HTTP users. Ifhtpasswd
cannot access a file, such as not being able to write to the output file or not being able to read the file in order to update it, it returns an error status and makes no changes.
Portainer
Portainer is a lightweight management UI which allows you to easily manage your different Docker environments. It consists of a single container that can run on any Docker engine. Portainer allows you to manage all your Docker resources (containers, images, volumes, networks and more) ! It is compatible with the standalone Docker engine and with Docker Swarm mode
Docker-compose
Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.
See Docker and Docker-compose installation instructions here
Setting Up
Creating Directories
Running the following commands to create the required directories
mkdir -p /opt/docker/registry/data
mkdir -p /opt/docker/registry/certs
mkdir -p /opt/docker/registry/auth
mkdir -p /opt/docker/compose
mkdir -p /opt/docker/portainer
mkdir -p /opt/docker/ssl/
Installations
Run the following commands to install required software
Install Htpasswd: yum provides \*bin/htpasswd
Install Git: yum install git -y
Create password File for Docker Registry Basic Auth
Run the following commands
- Change directory:
cd /opt/docker/registry/auth
- Create password file:
htpasswd -Bc htpasswd admin
- Follow the prompt to create a password
Please note:
- The above command will use
htpasswd
to create a file calledhtpasswd
. admin
is the user we’ll use for the registry. Feel free to choose any name.
Setting Up a Container to Generate HTTPS Certificates
Josh Wulf has a very cool article to set this up, so we’ll be very brief, check it out here.
- Change directory:
cd /opt/docker/ssl/
- Clone
git clone https://github.com/jwulf/letsencrypt-nginx-sidecar.git
- Change directory:
cd letsencrypt-nginx-sidecar/
- Create network for containers:
docker network create letsencrypt
- Change directory & start containers:
cd sidecar && docker-compose up -d
Assuming your server hostname is: domain.example.com and you have containers running, The above commands should result in a creation of certificates files and keys in the directory: /opt/docker/ssl/letsencrypt-nginx-sidecar/sidecar/certs/domain.example.com
. We’ll use this location in the next section.
NB: For certs to generate, run the next step first without the following command, maybe comment it out temporarily: command: — ssl — sslcert /certs/fullchain.pem — sslkey /certs/key.pem
Setting Up a Containers to Use Generated HTTPS Certificates
Last step is to create a compose file and run
- Change directory:
cd /opt/docker/compose
- Create a compose file:
vi docker-compose.yml
- Copy the contents of the file below into the file you created
Remember to change the following in both the Portainer and Docker registry sections:
- Env variable:
VIRTUAL_HOST
to your server hostname - Env variable:
LETSENCRYPT_HOST
to your server hostname - Env variable:
LETSENCRYPT_EMAIL
to your email address - Volume: The server hostname is also referenced in the volumes, please change it to your server name instead of
domain.example.com
You can now do the following:
- For Portainer, navigate to https://domain.example.com:9000 — Set up a new password and start managing your containers
- For the registry, run docker login https://domain.example.com:5000 — use the username password created in the Create password File for Docker Registry Basic Auth section above.