Install Docker Trusted Registry

Estimated reading time: 5 minutes

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

Since DTR requires Docker Universal Control Plane (UCP) to run, you need to install UCP on all the nodes where you plan to install DTR.

DTR needs to be installed on a worker node that is being managed by UCP. You cannot install DTR 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.

$ docker run -it --rm \
  docker/dtr:2.7.1 install \
  --dtr-external-url <dtr.example.com> \
  --ucp-node <ucp-node-name> \
  --ucp-username admin \
  --ucp-url <ucp-url>

You can run the DTR install command on any node with the Docker Engine installed, ensure this node also has connectivity to the UCP Cluster. 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.

As an 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.

To install a specific version of DTR, replace 2.7.1 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. Using the --dtr-external-url <dtr-domain>:<port> optional flag during installation, or during a reconfiguration, so that UCP is automatically reconfigured to trust DTR.

To verify, 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.

Additionally, 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.

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:

  1. Load your UCP user bundle.

  2. Run the join command.

    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.

    Then run:

    docker run -it --rm \
      docker/dtr:2.7.1 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.

  3. 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