secure-docker-registry

This repository is intended to provide an easy way to deploy a secure docker registry using Nginx and authentication using HTTP BASIC.

To deploy a secure docker registry, you'll need a SSL certificate. This repository explains how to generate your own SSL certificate using certbot.

Any suggestions or issues are welcome in the issue navigator.
No more bullshit, It's only five steps and I hope you enjoy the tutorial.

Before start, we assume:

• You have a domain. In this tutorial, we'll be referencing it as $YOUR_DOMAIN;
• You have a remote linux machine using $YOUR_DOMAIN and no services running on it;
• You have docker-compose and docker-machine installed in your local machine.

Step 1: Clone and override

First, you'll need to clone this repository into your machine. All the next steps will be executed inside the project folder.

$ git clone https://github.com/Tiago-Lira/secure-docker-registry.git
Cloning into 'secure-docker-registry'...
remote: Counting objects: 11, done.
remote: Compressing objects: 100% (7/7), done.
remote: Total 11 (delta 0), reused 11 (delta 0), pack-reused 0
Unpacking objects: 100% (11/11), done.
Checking connectivity... done.
$ cd secure-docker-registry/

Then, open the Nginx configuration file at nginx/registry.conf, and override the $YOUR_DOMAIN variable to your own domain.

# nginx/registry.conf

- line 9: server_name $YOUR_DOMAIN;
+ line 9: server_name yourdomain.com;

- line 101: server_name $YOUR_DOMAIN;
+ line 101: server_name yourdomain.com;

Step 2: Create your own SSL Certificate

You can skip this step if you already have your SSL certificate. In this step we are assuming that your remote machine is using ubuntu 16.04. But don't worry, for other operating systems you can follow the official tutorial. Remmember to select Nginx and your Operating System. Don't forget to run the openssl command and override $YOUR_DOMAIN because it isn't in the certbot tutorial.

$ ssh root@$YOUR_DOMAIN
Welcome to Ubuntu 16.04.1 LTS (GNU/Linux 4.4.0-45-generic x86_64)
$YOUR_DOMAIN~# sudo apt-get install letsencrypt
$YOUR_DOMAIN~# letsencrypt certonly --standalone -d $YOUR_DOMAIN -d www.$YOUR_DOMAIN
IMPORTANT NOTES:
 - If you lose your account credentials, you can recover through
   e-mails sent to $YOUR_EMAIL.
 - Congratulations! Your certificate and chain have been saved at
   /etc/letsencrypt/live/$YOUR_DOMAIN/fullchain.pem. Your
   cert will expire on $DATE. To obtain a new version of the
   certificate in the future, simply run Let's Encrypt again.
 - Your account credentials have been saved in your Let's Encrypt
   configuration directory at /etc/letsencrypt. You should make a
   secure backup of this folder now. This configuration directory will
   also contain certificates and private keys obtained by Let's
   Encrypt so making regular backups of this folder is ideal.
 - If you like Let's Encrypt, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
   Donating to EFF:                    https://eff.org/donate-le
$YOUR_DOMAIN~# openssl dhparam -out /etc/letsencrypt/archive/$YOUR_DOMAIN/dhparam.pem 2048
$YOUR_DOMAIN~# exit
Connection to $YOUR_DOMAIN closed.

Keep in mind that the folder /etc/letsencrypt is important, I recommend you make a backup of this folder.

Step 3: Download your certificate files to your registry folder

At the root of this project, run a scp command to download the main files generated by the previous step. Then, run ls ./nginx/security and you must have five files .pem.

$ scp root@$YOUR_DOMAIN:/etc/letsencrypt/archive/$YOUR_DOMAIN/* ./nginx/security/
$ ls ./nginx/security/
cert1.pem       dhparam.pem  git.empty  chain1.pem
fullchain1.pem  privkey1.pem

Step 4: Create a docker-machine

We need the docker-machine script to run docker-compose in your remote server. The command bellow will create a link between your shell and your remote machine to run docker commands there. Is not required to have docker installed in your remote machine. docker-machine will do it for you.

$ docker-machine create -d generic --generic-ip-address=$YOUR_DOMAIN registry
Running pre-create checks...
Creating machine...
Waiting for machine to be running, this may take a few minutes...
Detecting operating system of created instance...
Waiting for SSH to be available...
Detecting the provisioner...
Provisioning with ubuntu(systemd)...
Installing Docker...
Copying certs to the local machine directory...
Copying certs to the remote machine...
Setting Docker configuration on the remote daemon...
Checking connection to Docker...
Docker is up and running!
To see how to connect your Docker Client to the Docker Engine running on this virtual machine, run:
docker-machine env registry

Step 5: Deploy your registry

Okay, now we have all things required to run our secure docker registry. To deploy our registry, activate your docker-machine and run docker-compose up. After this, you'll be able to access your docker registry at https://$YOUR_DOMAIN/v2/. The credentials to log in are admin and registry.

$ eval $(docker-machine env registry)
$ docker-compose up -d
registry uses an image, skipping
Building registry-nginx
Step 1 : FROM nginx:stable
 ---> 9bd6b3c63114
Step 2 : RUN rm /etc/nginx/conf.d/default.conf
 ---> 43b9ce488a59
Step 3 : COPY registry.conf /etc/nginx/conf.d/registry.conf
 ---> 72d64117c070
Step 4 : COPY registry.password /etc/nginx/conf.d/registry.password
 ---> f32da394c343
Step 5 : COPY ./security/dhparam.pem /etc/nginx/security/dhparam.pem
 ---> 945c50a54941
Step 6 : COPY ./security/fullchain.pem /etc/nginx/security/fullchain.pem
 ---> 8ac9194c0cf6
Step 7 : COPY ./security/privkey.pem /etc/nginx/security/privkey.pem
 ---> 6bff82c844e0
Successfully built 6bff82c844e0

That's it, I hope you've enjoyed. The documentation to use the docker registry is here https://blog.docker.com/2013/07/how-to-use-your-own-registry/.

Futher steps

If you need another username and password, you'll have to install apache-utils in your machine. After installing it, run this command:

$ cd secure-docker-registry/nginx
$ htpasswd -c registry.password $USERNAME
New password:

Roadmap

• Create a fabric script to create the SSL certificate in a remote machine
• Create a fabric script to renew the SSL certificate