docs/install.md

+++ title = "Installation" description = "Installation instructions for Docker Trusted Registry" keywords = ["docker, documentation, about, technology, understanding, enterprise, hub, registry"] [menu.main] parent="smn_dhe" weight=4 +++

Install Docker Trusted Registry

This document describes the process of obtaining, installing, and securing Docker Trusted Registry . Docker Trusted Registry is installed from Docker containers. Once installed, you will need to select a method of securing it. This doc will explain the options you have for security and help you find the resources needed to configure it according to your chosen method. More configuration details can be found in the [Docker Trusted Registry Configuration page]({{< relref "configuration.md" >}}).

Specifically, installation requires completion of these steps, in order:

1. Acquire a license by purchasing Docker Trusted Registry or signing up for a trial license.
2. Install the commercially supported Docker Engine.
3. Install Docker Trusted Registry
4. Add your license to your Docker Trusted Registry instance

To get your copy of Docker Trusted Registry, including a free trial, visit the Docker Subscription page.

Licensing

In order to run Docker Trusted Registry, you will need to get a license, either by purchasing Docker Trusted Registry or acquiring a trial license. The license will be associated with your free Docker Hub account or Docker Hub organization (so if you don't have an account, you'll need to set one up, which can be done at the same time as your license request). To get your license, visit the Docker Subscription page and select the edition you would like acquire. After completing a brief registration process, follow the steps to acquire a license.

Once you've acquired your license, you can view or download it by logging in to Docker Hub, going to your account settings (gear icon at upper right), and then selecting "Licenses" from the top nav bar.

The Licenses page will display your currently available licenses. Click the cloud icon to download your desired license. You may need to disable any pop-up blocker installed on your browser in order to complete the download.

You can also download the commercially supported Docker Engine packages from this page by clicking the download buttons at upper right (see below for details).

Prerequisites

Docker Trusted Registry runs on the following platforms:

• Ubuntu 14.04 LTS
• RHEL 7.0 and 7.1
• CentOS 7.1

Docker Trusted Registry 1.3.0 requires the following:

• Commercially supported Docker Engine, preferably 1.6.2-cs5 or later, running on a supported host. (See below for instructions on how to install the commercially supported Docker Engine.)

Note: In order to remain in compliance with your Docker Trusted Registry support agreement, you must use the current version of commercially supported Docker Engine. Running the open source version of Engine is not supported.

• Your Docker daemon needs to be listening to the Unix socket (the default) so that it can be bind-mounted into the Docker Trusted Registry management containers, allowing Docker Trusted Registry to manage itself and its updates. For this reason, your Docker Trusted Registry host will also need internet connectivity so it can access the updates.

• Your host also needs to have TCP ports 80 and 443 available for the Docker Trusted Registry container port mapping.

• You will also need the Docker Hub user-name and password used when obtaining the Docker Trusted Registry license (or the user-name of an administrator of the Hub organization that obtained an Enterprise license).

Installing the commercially supported Docker Engine

Since Docker Trusted Registry is installed using Docker, the commercially supported Docker Engine must be installed first. This is done with an RPM or DEB package, which you access using a script downloaded from your Docker Hub Licenses page.

Download the commercially supported Docker Engine installation script

To download the commercially supported Docker Engine Bash installation script, log in to the Docker Hub with the user-name used to obtain your license . Once you're logged in, go to the "Licenses" page in your Hub account's "Settings" section (accessed via the gear icon at upper right).

Click the button at the top right of the page that corresponds to your intended host operating system. and then, once the Bash setup script is downloaded, follow the steps below appropriate for your chosen OS.

CentOS 7.1 & RHEL 7.0/7.1 installation

First, copy the downloaded Bash setup script to your RHEL host. Next, run the following to install commercially supported Docker Engine and its dependencies, and then start the Docker daemon:

$ sudo yum update && sudo yum upgrade
$ chmod 755 docker-cs-engine-rpm.sh
$ sudo ./docker-cs-engine-rpm.sh
$ sudo yum install docker-engine-cs
$ sudo systemctl enable docker.service
$ sudo systemctl start docker.service

In order to simplify using Docker, you can get non-sudo access to the Docker socket by adding your user to the docker group, then logging out and back in again:

$ sudo usermod -a -G docker $USER
$ exit

Note

: you may need to reboot your server to update its RHEL kernel.

Note

: CentOS 7.0 is not supported.

Ubuntu 14.04 LTS installation

First, copy the downloaded Bash setup script to your Ubuntu host. Next, run the following to install commercially supported Docker Engine and its dependencies:

$ sudo apt-get update && sudo apt-get upgrade
$ sudo apt-get install -y linux-image-extra-virtual
$ sudo reboot
$ chmod 755 docker-cs-engine-deb.sh
$ sudo ./docker-cs-engine-deb.sh
$ sudo apt-get install docker-engine-cs

Lastly, confirm Docker is running with sudo service docker start.

In order to simplify using Docker, you can get non-sudo access to the Docker socket by adding your user to the docker group, then logging out and back in again:

$ sudo usermod -a -G docker $USER
$ exit

Note

: you may need to reboot your server to update its LTS kernel.

Upgrading the commercially supported Docker Engine

CS Docker Engine 1.6.2cs6 contains fixes issues in 1.6.1, and customers should upgrade to it immediately.

Note

: If you have CS Docker Engine 1.6.0 installed, it must be upgraded; however, due to compatibility issues, Docker Trusted Registry must be upgraded first.

The CS Docker Engine installation script set up the RHEL/Ubuntu package repositories, so upgrading the Engine only requires you to run the update commands on your server.

CentOS 7.1 & RHEL 7.0/7.1 upgrade

The following commands will stop the running Docker Trusted Registry, upgrade CS Docker Engine, and then start Docker Trusted Registry again:

    $ sudo bash -c "$(sudo docker run docker/trusted-registry stop)"
    $ sudo yum update
    $ sudo systemctl daemon-reload && sudo systemctl restart docker
    $ sudo bash -c "$(sudo docker run docker/trusted-registry start)"

Ubuntu 14.04 LTS upgrade

The following commands will stop the running Docker Trusted Registry, upgrade CS Docker Engine, and then start Docker Trusted Registry again:

    $ sudo bash -c "$(sudo docker run docker/trusted-registry stop)"
    $ sudo apt-get update && sudo apt-get dist-upgrade docker-engine-cs
    $ sudo bash -c "$(sudo docker run docker/trusted-registry start)"

Installing Docker Trusted Registry

Once the commercially supported Docker Engine is installed, you can install Docker Trusted Registry itself. Docker Trusted Registry is a self-installing application built and distributed using Docker and the Docker Hub. It is able to restart and reconfigure itself using the Docker socket that is bind-mounted to its container.

Start installing Docker Trusted Registry by running the "docker/trusted-registry" container:

	$ sudo bash -c "$(sudo docker run docker/trusted-registry install)"

Note

: sudo is needed for docker/trusted-registry commands to ensure that the Bash script is run with full access to the Docker host.

The command will execute a shell script that creates the needed directories and then runs Docker to pull Docker Trusted Registry's images and run its containers.

Depending on your internet connection, this process may take several minutes to complete.

A successful installation will pull a large number of Docker images and should display output similar to:

$ sudo bash -c "$(sudo docker run docker/trusted-registry install)"
Unable to find image 'docker/trusted-registry:latest' locally
Pulling repository docker/trusted-registry
c46d58daad7d: Pulling image (latest) from docker/trusted-registry
c46d58daad7d: Pulling image (latest) from docker/trusted-registry
c46d58daad7d: Pulling dependent layers
511136ea3c5a: Download complete
fa4fd76b09ce: Pulling metadata
fa4fd76b09ce: Pulling fs layer
ff2996b1faed: Download complete
...
fd7612809d57: Pulling metadata
fd7612809d57: Pulling fs layer
fd7612809d57: Download complete
c46d58daad7d: Pulling metadata
c46d58daad7d: Pulling fs layer
c46d58daad7d: Download complete
c46d58daad7d: Download complete
Status: Downloaded newer image for docker/trusted-registry:latest
Unable to find image 'docker/trusted-registry:1.1.0' locally
Pulling repository docker/trusted-registry
c46d58daad7d: Download complete
511136ea3c5a: Download complete
fa4fd76b09ce: Download complete
1c8294cc5160: Download complete
117ee323aaa9: Download complete
2d24f826cb16: Download complete
33bfc1956932: Download complete
48f0dd6c9414: Download complete
65c30f72ecb2: Download complete
d4b29764d0d3: Download complete
5654f4fe5384: Download complete
9b9faa6ecd11: Download complete
0c275f56ca5c: Download complete
ff2996b1faed: Download complete
fd7612809d57: Download complete
Status: Image is up to date for docker/trusted-registry:1.1.0
INFO  [1.0.0_8ce62a61e058] Attempting to connect to docker engine dockerHost="unix:///var/run/docker.sock"
INFO  [1.0.0_8ce62a61e058] Running install command
<...output truncated...>
Creating container docker_trusted_registry_load_balancer with docker daemon unix:///var/run/docker.sock
Starting container docker_trusted_registry_load_balancer with docker daemon unix:///var/run/docker.sock
Bringing up docker_trusted_registry_log_aggregator.
Creating container docker_trusted_registry_log_aggregator with docker daemon unix:///var/run/docker.sock
Starting container docker_trusted_registry_log_aggregator with docker daemon unix:///var/run/docker.sock
$ docker ps
CONTAINER ID        IMAGE                                          COMMAND                CREATED             STATUS              PORTS                                      NAMES
963ec2a4b047        docker/trusted-registry-nginx:1.1.0            "nginxWatcher"         5 minutes ago       Up 5 minutes        0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp   docker_trusted_registry_load_balancer
7eade5529049        docker/trusted-registry-distribution:v2.0.1    "registry /config/st   5 minutes ago       Up 5 minutes        5000/tcp                                   docker_trusted_registry_image_storage_0
b968a8a986f9        docker/trusted-registry-distribution:v2.0.1    "registry /config/st   5 minutes ago       Up 5 minutes        5000/tcp                                   docker_trusted_registry_image_storage_1
390d9d68a33a        docker/trusted-registry-admin-server:1.1.0     "server"               5 minutes ago       Up 5 minutes        80/tcp                                     docker_trusted_registry_admin_server
3f8a53dc5f35        docker/trusted-registry-log-aggregator:1.1.0   "log-aggregator"       5 minutes ago       Up 5 minutes                                                   docker_trusted_registry_log_aggregator
44083421fa16        docker/trusted-registry-garant:1.1.0           "garant /config/gara   5 minutes ago       Up 5 minutes                                                   docker_trusted_registry_auth_server
c4102adf73dc        postgres:9.4.1                                 "/docker-entrypoint.   5 minutes ago       Up 5 minutes        5432/tcp                                   docker_trusted_registry_postgres

Once this process completes, you should be able to manage and configure your Docker Trusted Registry instance by pointing your browser to https://<host-ip>/.

Your browser will warn you that this is an unsafe site, with a self-signed, untrusted certificate. This is normal and expected; allow this connection temporarily.

Setting the Docker Trusted Registry Domain Name

The Docker Trusted Registry Administrator site will also warn that the "Domain Name" is not set. Select "Settings" from the global nav bar at the top of the page, and then set the "Domain Name" to the full host-name of your Docker Trusted Registry server. Clicking the "Save and Restart Docker Trusted Registry Server" button will generate a new certificate, which will be used by both the Docker Trusted Registry Administrator web interface and the Docker Trusted Registry server.

After the server restarts, you will again need to allow the connection to the untrusted Docker Trusted Registry web admin site.

Lastly, you will see a red warning notifying you that this instance of Docker Trusted Registry is unlicensed. You'll correct this in the next step.

Add your license

The Docker Trusted Registry services will not start until you add your license. To do that, you'll first download your license from the Docker Hub and then upload it to your Docker Trusted Registry web admin server. Follow these steps:

1. If needed, log back into the Docker Hub using the user-name you used when obtaining your license. Go to "Settings" (gear icon, top right) to get to your account settings, and then click on "Licenses" in the top nav bar.

2. You'll see a list of available licenses. Click on the download button to obtain the license file you'd like to use.

3. Next, go to your Docker Trusted Registry instance in your browser, click on "Settings" in the global nav bar and then click "License" in the Settings nav bar. Click the "Choose File" button, which will open a standard file browser. Locate and select the license file you downloaded in step 2, above. Approve the selection to close the dialog.

4. Click the "Save and restart" button, which will quit Docker Trusted Registry and then restart it, applying the new license.

5. Verify the acceptance of the license by confirming that the "Unlicensed copy" warning is no longer present.

Securing Docker Trusted Registry

Securing Docker Trusted Registry is required. You will not be able to push or pull from Docker Trusted Registry until you secure it.

There are several options and methods for securing Docker Trusted Registry. For more information, see the [configuration documentation]({{< relref "configuration.md#security" >}})

Using Docker Trusted Registry to push and pull images

Now that you have Docker Trusted Registry configured with a "Domain Name" and have your client Docker daemons configured with the required security settings, you can test your setup by following the instructions for [Using Docker Trusted Registry to Push and pull images]({{< relref "userguide.md" >}}).

Docker Trusted Registry web interface and registry authentication

By default, there is no authentication set on either the Docker Trusted Registry web admin interface or the Docker Trusted Registry. You can restrict access using an in-Docker Trusted Registry configured set of users (and passwords), or you can configure Docker Trusted Registry to use LDAP- based authentication.

See [Docker Trusted Registry Authentication settings]({{< relref "configuration.md#authentication" >}}) for more details.

Upgrading Docker Trusted Registry

Docker Trusted Registry has been designed to allow on-the-fly software upgrades. Start by loading the Docker Trusted Registry Dashboard in your browser and clicking "Settings" in the global nav bar. Then click "Updates" in the Settings nav bar. You'll see the currently installed version and a message telling you that the version is either current or that there is an update available.

If there is an update available, you will see the message "System Update Available" and a button labeled "Update to Version X.XX". Click the button to start the update process. To update, Docker Trusted Registry will pull new Docker Trusted Registry container images from the Docker Hub. If you have not already connected to Docker Hub, Docker Trusted Registry will prompt you to log in.

The upgrade process requires a small amount of downtime to complete. To complete the upgrade, Docker Trusted Registry will:

• Connect to the Docker Hub to pull new container images with the new version of Docker Trusted Registry.
• Deploy those containers
• Shut down the old containers
• Resolve any necessary links/urls.

Assuming you have a decent internet connection, the entire upgrade process should complete within a few minutes.

You should now upgrade CS Docker Engine if needed.

Note

: If Docker engine is upgraded first (Docker Trusted Registry 1.1 on CS Docker Engine 1.6.1), Docker Trusted Registry can still be upgraded from the command line by running:

sudo bash -c "$(sudo docker run docker/trusted-registry:1.1.0 upgrade 1.1.1)"

Next Steps

For information on configuring Docker Trusted Registry for your environment, take a look at the [Configuration instructions]({{< relref "configuration.md" >}}).