Docker Private Registry with S3 backend on AWS

5 minute read , May 03, 2017


Our current Docker Hub Registry at provides for a single private repository. This means all our private images must be stored there which prevents from proper versioning via labels. Setting up this repository is an alternative to using AWS ECR service for the same purpose.


S3 bucket

We start by creating S3 bucket for the Docker Registry:

$ aws s3api create-bucket --bucket my-bucket --region ap-southeast-2 --create-bucket-configuration LocationConstraint=ap-southeast-2
$ aws s3api put-bucket-versioning --region ap-southeast-2 --bucket my-bucket --versioning-configuration Status=Enabled

We create the bucket in the same region as our Git/Registry server and have versioning enabled so we can recover to previous state of the images in case of issues.

IAM Setup

Next is the IAM setup to control the bucket access. We add IAM Instance Profile that allows access to the DockerHub S3 bucket and attach it to the EC2 instance that will be running our Docker Registry. The json file DockerHubS3Policy.json looks like:

  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Action": [
      "Resource": "arn:aws:s3:::my-bucket"
      "Effect": "Allow",
      "Action": [
      "Resource": "arn:aws:s3:::my-bucket/*"

Create the policy based on the json file we created:

$ aws iam create-policy --policy-name DockerHubS3Policy --policy-document file://DockerHubS3Policy.json

Now we create an IAM Role. First the policy file TrustPolicy.json:

  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Principal": {
        "Service": ""
      "Action": "sts:AssumeRole"

then we run:

$ aws iam create-role --role-name DockerHubS3Role --assume-role-policy-document file://TrustPolicy.json

Then we attach the Policy to the Role:

$ aws iam attach-role-policy --role-name DockerHubS3Role --policy-arn arn:aws:iam::xxxxxxxxxxxx:policy/DockerHubS3

Next we create Instance Profile and attach the Role to it:

$ aws iam create-instance-profile --instance-profile-name DockerHubS3Profile
$ aws iam add-role-to-instance-profile --role-name DockerHubS3Role --instance-profile-name DockerHubS3Profile

and finally we attach the IAM Instance Role to an existing EC2 instance that was originally launched without an IAM role:

$ aws ec2 associate-iam-instance-profile --instance-id i-91xxxxxx --iam-instance-profile Name=DockerHubS3Profile

Docker Registry Setup

The Registry server will be a Docker container runnig on our Git server.


Install docker:

root@git:~# curl -fsSL | sudo apt-key add -
root@git:~# add-apt-repository "deb [arch=amd64] $(lsb_release -cs) stable"
root@git:~# apt-get update && apt-get install docker-ce -y

Registry Server

Create a directory we are going to mount in the registry container:

root@git:~# mkdir -p /docker-registry

Create username and password for our registry:

root@git:~# docker run --rm --entrypoint htpasswd registry:2 -Bbn user "password" > /docker-registry/htpasswd
root@git:~# cat /docker-registry/htpasswd

And also copy the SSL certificate, containing our wildcard and complete CA chain, and the private SSL key over:

root@git:~# tree /docker-registry/
└── htpasswd
0 directories, 3 files

Now we can start our Private Registry server:

docker run -d -p 5000:5000 --privileged --restart=always --name s3-registry \
-v /docker-registry:/data:ro \
-e REGISTRY_STORAGE_S3_REGION=ap-southeast-2 \

The --restart=always will insure the container starts on reboot and stays running. Check the status:

root@git:~# docker ps
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
d5262ecc7096        registry:2          "/ /e..."   35 minutes ago      Up 35 minutes>5000/tcp   s3-registry
root@git:~# docker exec -it d5262ecc7096 registry --version
registry v2.6.1

Lets try to login:

root@git:/docker-registry# docker login -u user -p "password"
Login Succeeded

Lets try and push an image to the new registry. Download, tag and push an image:

root@git:~# docker pull alpine:3.4
root@git:~# docker tag alpine:3.4
root@git:~# docker images
REPOSITORY                          TAG                 IMAGE ID            CREATED             SIZE
registry                            2                   136c8b16df20        2 weeks ago         33.2 MB
alpine                              3.4                 245f7a86c576        7 weeks ago         4.81 MB        3.4                 245f7a86c576        7 weeks ago         4.81 MB
root@git:~# docker push
The push refers to a repository []
9f8566ee5135: Pushed
3.4: digest: sha256:16b343a6f04a2b2520cb1616081b2257530c942d875938da964a3a7d60f61930 size: 528

Lets check the repository now:

root@git:~# curl -sSNL -u 'user:password'

That’s it, our private repository S3 storage is working and we can see the Alpine image we just uploaded. Now we can store our images here, example of stunnel image I built on another server:

ubuntu@ip-172-31-1-215:~/ansible_docker/stunnel$ sudo docker tag encompass/stunnel:latest
ubuntu@ip-172-31-1-215:~/ansible_docker/stunnel$ sudo docker login
Username: user
Login Succeeded
ubuntu@ip-172-31-1-215:~/ansible_docker/stunnel$ sudo docker push
The push refers to a repository []
9ce9633b5c62: Pushed
b26e9b2dba3f: Pushed
b0adc271bdea: Pushed
62d4c3d22ff1: Pushed
58d5c6f69f4a: Pushed
0ee67ec08f79: Pushed
72bba1783479: Pushed
737167029b1e: Pushed
95ab35bd2ba1: Pushed
18254e9b079f: Pushed
2bee8e041459: Pushed
483f4516a316: Pushed
266c6f483d86: Pushed
3ca85353d859: Pushed
1771b91fd055: Pushed
c29b5eadf94a: Pushed
latest: digest: sha256:30e799a5a616afecd7bc0405032747aad25bbc12947cc18dd68927a77c2d47e3 size: 3661

Now we can see the stunnel repository as well:

root@git:~# curl -sSNL -u 'user:password'


For example to see the tags for a repository:

root@git:~# curl -sSNL -u 'user:password'

To get image details like size and digest we need to fetch its manifest:

root@git:~# curl -sSNL -u 'user:password' -H "Accept: application/vnd.docker.distribution.manifest.v2+json" -X GET
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
   "config": {
      "mediaType": "application/vnd.docker.container.image.v1+json",
      "size": 9356,
      "digest": "sha256:763aa8b1b75bb998871c5b434bb6218f4069bfd65cdf2f20ac933c5abadce489"
   "layers": [
root@git:~# curl -sSNL -u 'user:password' -H "Accept: application/vnd.docker.distribution.manifest.v2+json" -X GET
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
   "config": {
      "mediaType": "application/vnd.docker.container.image.v1+json",
      "size": 12031,
      "digest": "sha256:3606a1cf3ba3d74ccadf594d02598db2db1c536ae06f6eb58038eca258710def"
   "layers": [
         "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
         "size": 67088058,
         "digest": "sha256:3122919554d460a6ac9c1113a2a36d88318c94d41ed9bab9178622e9e8f31261"

Full docs for the API v2


The private registry offers Webhooks functionality via Notifications API. See for details.

Registry UI

In case we need UI for the registry the docker container is known for working fine. The image can be pulled from Since this app can be used as SSL proxy to the registry server we can simply disable the SSL in the registry it self and get it listen to localhost only. Then we start th UI container like:

root@git:~# docker run --privileged --restart=always \
 -d \
 -e \
 -e ENV_USE_SSL=yes \
 -v /data/ \
 -v /data/ \
 -p 443:443 \

and have our registry available via UI at To enable browse-only mode for our repository we can start with -e ENV_MODE_BROWSE_ONLY=true in the run command. The container supports Kerberos authentication only but its running Apache internally so it will not be difficult to clone the repository and modify the setup to install the ldap module for example so we can drop the registry authentication and integrate with a LDAP server.

Leave a Comment