Install Docker Trusted Registry

Estimated reading time: 6 minutes

This topic applies to Docker Enterprise.

The Docker Enterprise platform business, including products, customers, and employees, has been acquired by Mirantis, inc., effective 13-November-2019. For more information on the acquisition and how it may affect you and your business, refer to the Docker Enterprise Customer FAQ.

Docker Trusted Registry (DTR) is a containerized application that runs on a swarm managed by the Universal Control Plane (UCP). It can be installed on-premises or on a cloud infrastructure.

Step 1. Validate the system requirements

Before installing DTR, make sure your infrastructure meets the system requirements that DTR needs to run.

Step 2. Install UCP

DTR requires Docker Universal Control Panel (UCP) to run. If UCP is not yet installed, refer to install UCP for production.

Note

Prior to installing DTR:

When upgrading, upgrade UCP before DTR for each major version. For example, if you are upgrading four major versions, upgrade one major version at a time, first UCP, then DTR, and then repeat for the remaining three versions.

UCP upgraded to the most recent version before an initial install of DTR.

Docker Engine should be updated to the most recent version before installing or updating UCP.

DTR and UCP must not be installed on the same node, due to the potential for resource and port conflicts. Instead, install DTR on worker nodes that will be managed by UCP. Note also that DTR cannot be installed on a standalone Docker Engine.

Step 3. Install DTR

Once UCP is installed, navigate to the UCP web interface as an admin. Expand your profile on the left navigation pane, and select Admin Settings > Docker Trusted Registry.
After you configure all the options, you should see a Docker CLI command that you can use to install DTR. Before you run the command, take note of the --dtr-external-url parameter:
```
   $ docker run -it --rm \
     docker/dtr:2.7.6 install \
     --dtr-external-url <dtr.example.com> \
     --ucp-node <ucp-node-name> \
     --ucp-username admin \
     --ucp-url <ucp-url>
```
If you want to point this parameter to a load balancer that uses HTTP for health probes over port 80 or 443, temporarily reconfigure the load balancer to use TCP over a known open port. Once DTR is installed, you can configure the load balancer however you need to.
Run the DTR install command on any node connected to the UCP cluster, and with the Docker Engine installed. DTR will not be installed on the node you run the install command on. DTR will be installed on the UCP worker defined by the --ucp-node flag.

For example, you could SSH into a UCP node and run the DTR install command from there. Running the installation command in interactive TTY or -it mode means you will be prompted for any required additional information. Learn more about installing DTR.

Here are some useful options you can set during installation:
- To install a specific version of DTR, replace 2.7.6 with your desired version in the installation command above. Find all DTR versions in the DTR release notes page.
- DTR is deployed with self-signed certificates by default, so UCP might not be able to pull images from DTR. Use the --dtr-external-url <dtr-domain>:<port> optional flag during installation, or during a reconfiguration, so that UCP is automatically reconfigured to trust DTR.
- With DTR 2.7, you can enable browser authentication via client certificates at install time. This bypasses the DTR login page and hides the logout button, thereby skipping the need for entering your username and password.
Verify that DTR is installed. Either:
- See https://<ucp-fqdn>/manage/settings/dtr, or;
- Navigate to Admin Settings > Docker Trusted Registry from the UCP web UI. Under the hood, UCP modifies /etc/docker/certs.d for each host and adds DTR’s CA certificate. UCP can then pull images from DTR because the Docker Engine for each node in the UCP swarm has been configured to trust DTR.
Reconfigure your load balancer back to your desired protocol and port.

Step 4. Check that DTR is running

In your browser, navigate to the UCP web interface.
Select Shared Resources > Stacks from the left navigation pane. You should see DTR listed as a stack.
To verify that DTR is accessible from the browser, enter your DTR IP address or FQDN on the address bar. Since HSTS (HTTP Strict-Transport-Security) header is included in all API responses, make sure to specify the FQDN (Fully Qualified Domain Name) of your DTR prefixed with https://, or your browser may refuse to load the web interface.

Step 5. Configure DTR

After installing DTR, you should configure:

The certificates used for TLS communication. Learn more.
The storage backend to store the Docker images. Learn more.

Web interface

To update your TLS certificates, access DTR from the browser and navigate to System > General.
To configure your storage backend, navigate to System > Storage. If you are upgrading and changing your existing storage backend, see Switch storage backends for recommended steps.

Command line interface

To reconfigure DTR using the CLI, see the reference page for the reconfigure command.

Step 6. Test pushing and pulling

Now that you have a working installation of DTR, you should test that you can push and pull images:

Step 7. Join replicas to the cluster

This step is optional.

To set up DTR for high availability, you can add more replicas to your DTR cluster. Adding more replicas allows you to load-balance requests across all replicas, and keep DTR working if a replica fails.

For high-availability, you should set 3 or 5 DTR replicas. The replica nodes also need to be managed by the same UCP.

To add replicas to a DTR cluster, use the join command:

Load your UCP user bundle.
Run the join command.
```
docker run -it --rm \
  docker/dtr:2.7.6 join \
  --ucp-node <ucp-node-name> \
  --ucp-insecure-tls
```
--ucp-node

The <ucp-node-name> following the --ucp-node flag is the target node to install the DTR replica. This is NOT the UCP Manager URL.

When you join a replica to a DTR cluster, you need to specify the ID of a replica that is already part of the cluster. You can find an existing replica ID by going to the Shared Resources > Stacks page on UCP.
Check that all replicas are running.

In your browser, navigate to UCP’s web interface. Select Shared Resources > Stacks. All replicas should be displayed.

Where to go next

dtr, registry, install