docker/ucp join

Estimated reading time: 3 minutes

These are the docs for UCP version 1.1

To select a different version, use the selector below.

Join this engine to an existing UCP.


docker run --rm -it \
  --name ucp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker/ucp \
  join [command options]


When running the ‘join’ command, you must run this tool on the engine you wish to join to an existing UCP. The UCP controller must be running on a different engine. Both engines must have network visibility to each other and have the required ports open on their firewall settings. If your system has multiple IP addresses, you may need to specify the ‘–host-address’ option to ensure the correct address is used.

Ports: 443, 12376, 12379, 12380, 12381, 12382 and 2376 or the ‘–swarm-port’ from ‘install’

To enable high-availability, you must join at least one node with the ‘replica’ flag. When joining a replica, you may optionally provide a backup tar file containing the Root CA material from the initial controller saved via the ‘backup’ command. Only the Root CA material will be retrieved from that backup. Add the following volume mount: -v /path/to/my/backup.tar:/backup.tar


--debug, -DEnable debug.
--jsonlogProduce json formatted output for easier parsing.
--interactive, -iEnable interactive mode. You will be prompted to enter all required information.
--admin-usernameSpecify the UCP admin username [$UCP_ADMIN_USER]
--admin-passwordSpecify the UCP admin password [$UCP_ADMIN_PASSWORD]
--fresh-installDestroy any existing state and start fresh.
--san [--san option --san option]Additional Subject Alternative Names for certs (e.g. --san --san
--host-addressSpecify the visible IP/hostname for this node. (override automatic detection) [$UCP_HOST_ADDRESS]
--swarm-port "2376"Select what port to run the local Swarm manager on (default: 2376)
--controller-port "443"Select what port to run the local Controller on (default: 443)
--dns [--dns option --dns option]Set custom DNS servers for the UCP infrastructure containers.
--dns-opt [--dns-opt option --dns-opt option]Set DNS options for the UCP infrastructure containers.
--dns-search [--dns-search option --dns-search option]Set custom DNS search domains for the UCP infrastructure containers.
--registry-usernameSpecify the username to pull required images with [$REGISTRY_USERNAME]
--registry-passwordSpecify the password to pull required images with [$REGISTRY_PASSWORD]
--urlThe connection URL for the remote UCP controller [$UCP_URL]
--fingerprintThe fingerprint of the UCP controller you trust [$UCP_FINGERPRINT]
--replicaConfigure this node to be a UCP controller replica.
--external-server-cert(Replica only) Use externally signed certificates for the controller.
--pull "missing"Specify image pull behavior (‘always’, when ‘missing’, or ‘never’) (default: “missing”)
--passphraseDecrypt the Root CA tar file with the provided passphrase [$UCP_PASSPHRASE]
--skip-engine-discoveryDo not configure engine for clustering
join, ucp