Install Docker Trusted RegistryEstimated reading time: 6 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
Before 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 should be installed or 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.
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. Before you run the command, take note of the
$ docker run -it --rm \ docker/dtr:2.7.3 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
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
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
-itmode 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:
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:
Navigate to Admin Settings > Docker Trusted Registry from the UCP web UI. Under the hood, UCP modifies
/etc/docker/certs.dfor 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.
- 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.3 join \ --ucp-node <ucp-node-name> \ --ucp-insecure-tls
--ucp-nodeflag 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.