Install Docker Trusted RegistryEstimated 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
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
means you will be prompted for any required additional information. Learn
more about installing DTR.
DTR is deployed with self-signed certificates by default, so UCP might not be
able to pull images from DTR. Using the
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
/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
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.
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.
docker run -it --rm \ docker/dtr:2.7.1 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.
Check that all replicas are running.
In your browser, navigate to UCP’s web interface. Select Shared Resources > Stacks. All replicas should be displayed.