docker/ucp install

Estimated reading time: 3 minutes

These are the docs for UCP version 2.0

To select a different version, use the selector below.

Install UCP on this node


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


This command initializes a new swarm, turns this node into a manager, and installs Docker Universal Control Plane (UCP).

When installing UCP you can customize:

  • The certificates used by the UCP web server. Create a volume named ‘ucp-controller-server-certs’ and copy the ca.pem, cert.pem, and key.pem files to the root directory. Then run the install command with the ‘–external-server-cert’ flag.

  • The license used by UCP, by bind-mounting the file at ‘/config/docker_subscription.lic’ in the tool. E.g. -v /path/to/my/config/docker_subscription.lic:/config/docker_subscription.lic

  • The initial users, permissions and settings of the system, using a backup of an existing UCP cluster. Bind-mount the backup file under ‘/config/backup.tar’ in the tool and use the ‘–from-backup’ flag. When using the ‘–from-backup’ flag, all other configuration flags are respected, except for the ‘–admin-username’ and ‘–admin-password’ flags.

If you’re joining more nodes to this swarm, open the following ports in your firewall:

  • 443 or the ‘–controller-port’
  • 2376 or the ‘–swarm-port’
  • 12376, 12379, 12380, 12381, 12382, 12383, 12384, 12385, 12386
  • 4789 (udp) and 7946 (tcp/udp) for overlay networking


--debug, DEnable debug mode
--jsonlogProduce json formatted output for easier parsing
--interactive, iRun in interactive mode and prompt for configuration values
--admin-usernameThe UCP administrator username
--admin-passwordThe UCP administrator password
--sanAdd subject alternative names to certificates (e.g. –san –san
--host-addressThe network address to advertise to other nodes. Format: IP address or network interface name
--swarm-portPort for the Docker Swarm manager. Used for backwards compatibility
--controller-portPort for the web UI and API
--swarm-grpc-portPort for communication between nodes
--dnsSet custom DNS servers for the UCP containers
--dns-optSet DNS options for the UCP containers
--dns-searchSet custom DNS search domains for the UCP containers
--pullPull UCP images: ‘always’, when ‘missing’, or ‘never’
--registry-usernameUsername to use when pulling images
--registry-passwordPassword to use when pulling images
--kv-timeoutTimeout in milliseconds for the key-value store
--kv-snapshot-countNumber of changes between key-value store snapshots
--from-backupInitialize a system from a backup of a UCP cluster
--passphraseThe passphrase needed to decrypt the backup file. To be used together with –from-backup if the backup is encrypted.
--swarm-experimentalEnable Docker Swarm experimental features. Used for backwards compatibility
--disable-trackingDisable anonymous tracking and analytics
--disable-usageDisable anonymous usage reporting
--external-server-certCustomize the certificates used by the UCP web server
--preserve-certsDon’t generate certificates if they already exist
--binpackSet the Docker Swarm scheduler to binpack mode. Used for backwards compatibility
--randomSet the Docker Swarm scheduler to random mode. Used for backwards compatibility
--external-service-lbSet the external service load balancer reported in the UI
--enable-profilingEnable performance profiling
docker, dtr, cli, install