Adds docs missing for 1.1.0

* closes #938
* closes #1252
* closes #1318
* closes #448
* closes #1465
* closes #1317
* closes #912
* closes #1473

access-ucp/index.md

@@ -9,3 +9,10 @@ identifier="mn_ucp_access"
 weight=31
 +++
 <![end-metadata]-->
+
+# Access UCP
+
+This section includes the following topics:
+
+* [Web-based access](web-based-access.md)
+* [CLI-based access](cli-based-access.md)

applications/index.md

@@ -9,3 +9,10 @@ identifier="mn_ucp_applications"
 weight=80
 +++
 <![end-metadata]-->
+
+# UCP applications
+
+This section includes the following topics:
+
+* [Deploy an app from the UI](deploy-app-ui.md)
+* [Deploy an app from the CLI](deploy-app-cli.md)

configuration/index.md

@@ -9,3 +9,11 @@ identifier="mn_ucp_configuration"
 weight=50
 +++
 <![end-metadata]-->
+
+# UCP configuration
+
+This section includes the following topics:
+
+* [Set up container networking](multi-host-networking.md)
+* [Integrate with Docker Trusted Registry](dtr-integration.md)
+* [Configure UCP logging](configure-logs.md)

high-availability/backups-and-disaster-recovery.md

@@ -20,13 +20,7 @@ The next step is creating a backup policy and disaster recovery plan.
 
 ## Backup policy
 
-Docker UCP nodes persist data using [named volumes](../architecture.md):
+Docker UCP nodes persist data using [named volumes](../architecture.md).
-
-* Controller nodes persist cluster configurations, certificates, and keys
-used to issue certificates and user bundles. This data is replicated on every
-controller node in the cluster.
-* Nodes are stateless. They only store certificates for mutual TLS, that
-can be regenerated.
 
 As part of your backup policy you should regularly create backups of the
 controller nodes. Since the nodes used for running user containers don't
@@ -46,19 +40,7 @@ To have minimal impact on your business, you should:
 * Configure UCP for high availability. This allows load-balancing user requests
 across multiple UCP controller nodes.
 
-## Backup UCP data
+## Backup command
-
-To learn about the options available on the `docker/ucp backup` command, you can
-check the reference documentation, or run:
-
-```bash
-$ docker run --rm docker/ucp backup --help
-```
-
-When creating a backup, the resulting tar archive contains sensitive information
-like private keys. To ensure this information is kept private you should run
-the backup command with the `--passphrase` option. This encrypts
-the backup with a passphrase of your choice.
 
 The example below shows how to create a backup of a UCP controller node:
 
@@ -68,14 +50,6 @@ $ docker run --rm -i --name ucp \
   -v /var/run/docker.sock:/var/run/docker.sock \
   docker/ucp --interactive --passphrase "secret" > /tmp/backup.tar
 
-Do you want proceed with the backup? (y/n):
-$ y
-
-INFO[0000] Temporarily Stopping local UCP containers to ensure a consistent backup
-INFO[0000] Beginning backup
-INFO[0001] Backup completed successfully
-INFO[0002] Resuming stopped UCP containers
-
 # Decrypt the backup and list its contents
 $ gpg --decrypt /tmp/backup.tar | tar --list
 
@@ -89,6 +63,35 @@ Enter passphrase: secret
 # output snipped
 ```
 
+## Restore command
+
+The example below shows how to restore a UCP controller node from an existing
+backup:
+
+```bash
+$ docker run --rm -i --name ucp \
+  -v /var/run/docker.sock:/var/run/docker.sock  \
+  docker/ucp restore -i < backup.tar
+```
+
+
+## Restore your cluster
+
+Configuring UCP to have multiple controller nodes allows you tolerate a certain
+amount of node failures. If multiple nodes fail at the same time, causing the
+cluster to go down, you can use an existing backup to recover.
+
+As an example, if you have a cluster with three controller nodes, A, B, and C,
+and your most recent backup was of node A:
+
+1. Stop controllers B and C with the `stop` command,
+2. Restore controller A,
+3. Uninstall UCP from controllers B and C,
+4. Join nodes B and C to the cluster.
+
+You should now have your cluster up and running.
+
+
 ## Where to go next
 
 * [Set up high availability](set-up-high-availability.md)

high-availability/index.md

@@ -9,3 +9,11 @@ identifier="mn_ucp_high_availability"
 weight=60
 +++
 <![end-metadata]-->
+
+# Configure UCP for high availability
+
+This section includes the following topics:
+
+* [Set up high availability](set-up-high-availability.md)
+* [Replicate CAs for high availability](replicate-cas.md)
+* [Backups and disaster recovery](backups-and-disaster-recovery.md)

index.md

@@ -15,3 +15,15 @@ solution from Docker. You install it behind your firewall, and it helps you
 manage your whole cluster from a single place.
 
 The UCP documentation includes the following topics:
+
+* [Universal Control Plane overview](overview.md)
+* [Evaluate UCP in a sandbox](install-sandbox.md)
+* [Architecture](architecture.md)
+* [Installation](installation/system-requirements.md)
+* [Access UCP](access-ucp/web-based-access.md)
+* [Configuration](configuration/multi-host-networking.md)
+* [Monitor and troubleshoot](monitor/monitor-ucp.md)
+* [High availability](high-availability/set-up-high-availability.md)
+* [User management](user-management/manage-users.md)
+* [Applications](applications/deploy-app-ui.md)
+* [Release notes](release_notes.md)

installation/index.md

@@ -9,3 +9,15 @@ identifier="mn_ucp_installation"
 weight=30
 +++
 <![end-metadata]-->
+
+# Install UCP
+
+This section includes the following topics:
+
+* [System requirements](system-requirements.md)
+* [Plan a production installation](plan-production-install.md)
+* [Install UCP for production](install-production.md)
+* [Install offline](install-offline.md)
+* [License UCP](license.md)
+* [Upgrade UCP](upgrade.md)
+* [Uninstall UCP](uninstall.md)

installation/install-production.md

@@ -16,11 +16,13 @@ weight=20
 Docker Universal Control Plane (UCP) is a containerized application that can be
 installed on-premises or on a cloud infrastructure.
 
+## Step 1: Validate the system requirements
+
 The first step in installing UCP, is ensuring your
 infrastructure has all the [requirements UCP needs to run](system-requirements).
-Once that is done, use these instructions to install UCP.
 
-## Step 1: Install CS Docker on all nodes
+
+## Step 2: Install CS Docker on all nodes
 
 UCP requires you to install Docker CS Engine 1.10 or above on all nodes of
 your UCP cluster.
@@ -28,7 +30,7 @@ your UCP cluster.
 For each node that you want to add to the UCP cluster, install the CS Docker
 Engine.
 
-## Step 2: Customize named volumes
+## Step 3: Customize named volumes
 
 This step is optional.
 
@@ -40,7 +42,9 @@ If the volumes don't exist, when installing UCP they are
 created with the default volume driver and flags.
 
 
-## Step 3: Customize the CA used
+## Step 4: Customize the CA used
+
+This step is optional.
 
 The UCP cluster uses TLS to secure all communications. Two Certificate
 Authorities (CA) are used for this:
@@ -69,15 +73,11 @@ If you want to use your own certificates:
     | key.pem  | Your UCP controller private key.                               |
 
 
-## Step 4: Install the UCP controller
+## Step 5: Install the UCP controller
 
 To install UCP you use the `docker/ucp` image. This image has commands to
 install, configure, and backup UCP. To find what commands and options are
-available, check the [reference documentation](../reference/install.md), or run:
+available, check the [reference documentation](../reference/install.md).
-
-```bash
-$ docker run --rm -it docker/ucp --help
-```
 
 To install UCP:
 
@@ -91,47 +91,59 @@ To install UCP:
 
     ```bash
     $ docker run --rm -it --name ucp \
-      -v /var/run/docker.sock:/var/run/docker.sock
+      -v /var/run/docker.sock:/var/run/docker.sock \
-      docker/ucp install -i
+      docker/ucp install -i \
+      --host-address <$UCP_PUBLIC_IP>
     ```
 
-    If you are using server certificates signed by an external CA, include
+    Where:
-    the `--external-server-cert` option at the end of the command.
+
+    * i, specify to run the install command interactively,
+    * host-address, is the public IP where users or a load balancer can access
+    UCP,
+    * Also, include the `--external-server-cert` flag if you're using server
+    certificates signed by an external CA.
+
+    </br>
+    When installing Docker UCP, overlay networking is automatically configured
+    for you. If you are running Docker CS Engine 1.10, or have custom
+    configurations on your Docker CS Engine, you need to restart the Docker
+    daemon at this point.
+
 
 3. Check that the UCP web application is running.
 
     In your browser, navigate to the address where you've installed UCP.
-    If you're not using your own certificates, your browser warns that UCP is
+    If you're not using an external CA, your browser warns that UCP is
     an unsafe site.
 
     ![](../images/login.png)
 
-## Step 5: License your installation
+## Step 6: License your installation
 
 Now that your UCP controller is installed, you need to license it.
 [Learn how to license your installation](license.md).
 
-## Step 6: Backup the controller CAs
+## Step 7: Backup the controller CAs
 
-Docker UCP has support for high-availability. For an highly available
+This step is optional.
-installation, you add more controller nodes to the UCP cluster. The controller
+
-nodes are replicas of each other.
+For an highly available installation, you can add more controller nodes to
+the UCP cluster. The controller nodes are replicas of each other.
 [Learn more about high-availability](../high-availability/set-up-high-availability.md).
 
-When configuring UCP for high-availability, you need to ensure the CAs running
+For this, you need to make the CAs on each controller node, use the same
-on each UCP controller node are interchangeable. This is done by using the same
+root certificates and keys.
-certificates and keys for every CA on the cluster.
 [Learn how to replicate the CAs for high availability](../high-availability/replicate-cas.md).
 
-## Step 7: Add controller replicas to the UCP cluster
 
-To add more controller nodes to the cluster, use the
+## Step 8: Add controller replicas to the UCP cluster
-`docker/ucp join --replica` command. To find what commands and options are
-available, check the [reference documentation](../reference/join.md), or run:
 
-```bash
+This step is optional.
-$ docker run --rm -it docker/ucp join --help
+
-```
+For an highly available installation, you can add more controller nodes to
+the UCP cluster. For that, use the `docker/ucp join --replica` command.
+[Learn more about the join command](../reference/join.md).
 
 For each node that you want to install as a controller replica:
 
@@ -146,13 +158,13 @@ For each node that you want to install as a controller replica:
     ```bash
     $ docker run --rm -it --name ucp \
       -v /var/run/docker.sock:/var/run/docker.sock \
-      docker/ucp join -i --replica
+      docker/ucp join -i \
+      --replica
     ```
 
 3. Repeat steps 1 and 2 on the other nodes you want to set up as replicas.
+Make sure you set up 3, 5, or 7 controllers.
 
-    For high availability, make sure to set up 3, 5, or 7 controller nodes.
-    [Learn more about high-availability](../high-availability/set-up-high-availability.md).
 
 4. Check the cluster state.
 
@@ -161,7 +173,7 @@ For each node that you want to install as a controller replica:
     ![UCP nodes page](../images/replica-nodes.png)
 
 
-## Step 8: Add more nodes to the UCP cluster
+## Step 9: Add more nodes to the UCP cluster
 
 Now you can add additional nodes to your UCP cluster. These are the nodes that
 will be running your containers.
@@ -186,7 +198,7 @@ For each node that you want to add to your UCP cluster:
 
     ![UCP nodes page](../images/nodes-page.png)
 
-## Step 9. Download an admin user bundle
+## Step 10. Download a client certificate bundle
 
 To validate that your cluster is correctly configured, you should try accessing
 the cluster with the Docker CLI client. For this, you'll need to get a client

installation/plan-production-install.md

@@ -17,38 +17,83 @@ Docker Universal Control Plane can be installed on-premises, or
 on a virtual private cloud. If you've never used Docker UCP before,
 you should start by [installing it on a sandbox](../install-sandbox.md).
 
-To secure your data, Docker UCP is automatically set up to use mutual TLS on
+This article explains what you need to consider before deploying
-all communications. Before you install UCP, make sure you know:
+Docker Universal Control Plane.
 
-* The fully qualified domain names (FQDN) of the hosts where you'll install UCP,
+## System requirements
-* Their Subject Alternative Names (SANs).
 
-## Fully-qualified domain names
+Before installing UCP, you should make sure all nodes of your cluster
+comply with the [system requirements](system-requirements.md).
 
-When installing Docker UCP, the installer tries to find the fully-qualified
+## Hostname strategy
-domain names (FQDN) of your hosts.
 
-If the installer can't detect this automatically, or if you want to use a
+Docker UCP requires the Docker CS Engine to run. Before installing Docker CS
-different FQDN or IP address,  use the `--host-address` option when installing.
+Engine on the cluster nodes, you should plan for a common naming strategy.
-This option allows you to specify the IP or hostname that UCP is going to use
-to reach that host.
 
-If you're installing UCP on a cloud provider such as AWS or Digital Ocean,
+Decide if you want to use short hostnames like `engine01` or Fully Qualified
-you might need to create a private network for you UCP installation. In that
+Domain Names (FQDN) likes `engine01.docker.vm`. Independently of your choice,
-case, make sure all nodes of the cluster can communicate using their private
+ensure your naming strategy is consistent across the cluster, since UCP uses
-IPs.
+the hostnames.
+
+As an example, if your cluster has 4 hosts you can name them:
+
+```bash
+engine01.docker.vm
+engine02.docker.vm
+engine03.docker.vm
+engine04.docker.vm
+```
+
+## Load balancing strategy
+
+UCP Docker UCP does not include a load-balancer. You can configure your own
+load-balancer to balance user requests across all controller nodes.
+
+If you plan on using a load balancer, you need to decide whether you are going
+to add the nodes to the load balancer using their IP address, or their FQDN.
+Independently of what you choose, it should be consistent across the  nodes.
+
+After that, you should take note of all IPs or FQDNs before starting the
+installation.
+
+## Load balancing UCP and DTR
+
+By default, both UCP and DTR use port 443. If you plan on deploying UCP and DTR,
+your load balancer needs to distinguish traffic between the two by IP address
+or port number.
+
+* If you want to configure your load balancer to listen on port 443:
+    * Use one load balancer for UCP, and another for DTR,
+    * Use the same load balancer with multiple virtual IPs.
+* Configure your load balancer to expose UCP or DTR on a port other than 443.
 
 
-## Subject alternative names (SANs)
+## Using external CAs
 
-When joining new nodes to the cluster, UCP creates leaf certificates for that
+You can customize UCP to use certificates signed by an external Certificate
-node. Those certificates are then used by for communicating over mutual TLS
+Authority. If you decide to use your own CAs take in considerat that:
-with other members of the cluster.
 
-You can specify the subject alternative names (SANs) to be used in the
+* During the installation you need to copy the ca.pem, cert.pem, and key.pem
-certificate. If you are installing UCP interactively you'll be prompted for
+files across all controller hosts,
-this. You can also use the `--san` option when installing and joining nodes
+* The ca.pem is the root CA public certificate
-to the cluster.
+* The cert.pem is the server cert plus any intermediate CA public certificates,
+* The cert.pem should have SANs for all addresses used to reach UCP,
+* The key.pem is the server private key,
+
+You can have a certificate for each controller, with a common SAN. As an
+example, on a three node cluster you can have:
+
+* engine01.docker.vm with SAN ducp.docker.vm
+* engine02.docker.vm with SAN ducp.docker.vm
+* engine03.docker.vm with SAN ducp.docker.vm
+
+## File transfer across hosts
+
+Make sure you can transfer file between the hosts on the cluster. You will
+need to replicate CAs across controller nodes.
+
+For this, you can tools like `scp` or `rsync`, or configure the hosts to use
+a network file system.
 
 
 ## Where to go next

installation/system-requirements.md

@@ -30,22 +30,30 @@ all nodes must have:
 * Linux kernel version 3.10 or higher
 * CS Docker Engine version 1.10 or higher
 
+For highly-available installations, you also need a way to transfer files
+between hosts.
 
 ## Ports used
 
 When installing UCP on a host, make sure the following ports are open:
 
 | Hosts              | Direction | Port                | Purpose                                                                    |
-|:-------------------|:---------:|:--------------------|:------------------------------------------------------------|
+|:-------------------|:---------:|:--------------------|:---------------------------------------------------------------------------|
 | controllers        |    in     | 443  (configurable) | Web app and CLI client access to UCP.                                      |
-| controllers        |    in     | 2376 (configurable) | Swarm manager accepts requests from UCP controller.         |
+| controller         |    out    | 443                 | Send anonymous usage reports to Docker.                                    |
 | controllers, nodes |    in     | 2375                | Heartbeat for nodes, to ensure they are running.                           |
+| controllers        |    in     | 2376 (configurable) | Swarm manager accepts requests from UCP controller.                        |
+| controllers, nodes |  in, out  | 4789                | Overlay networking.                                                        |
+| controllers, nodes |  in, out  | 7946                | Overlay networking.                                                        |
 | controllers, nodes |    in     | 12376               | Proxy for TLS, provides access to UCP, Swarm, and Engine.                  |
 | controller         |    in     | 12379               | Internal node configuration, cluster configuration, and HA.                |
 | controller         |    in     | 12380               | Internal node configuration, cluster configuration, and HA.                |
 | controller         |    in     | 12381               | Proxy for TLS, provides access to UCP.                                     |
 | controller         |    in     | 12382               | Manages TLS and requests from swarm manager.                               |
-| controller         |    out    | 443                 | Send anonymous usage reports to Docker.                     |
+| controller         |    in     | 12383               | Used by the authentication storage backend.                                |
+| controller         |    in     | 12384               | Used by authentication storage backend for replication across controllers. |
+| controller         |    in     | 12385               | The port where the authentication API is exposed.                          |
+| controller         |    in     | 12386               | Used by the authentication worker.                                         |
 
 UCP collects anonymous usage metrics, to help us improve it. These metrics
 are entirely anonymous, don’t identify your company, users, applications,

installation/uninstall.md

@@ -18,17 +18,18 @@ Plane from a node. This command only removes the UCP containers, and doesn’t
 affect any other containers.
 
 To see what options are available in the uninstall command, check the
-[uninstall command reference](../reference/uninstall.md), or run:
+[uninstall command reference](../reference/uninstall.md).
-
-```bash
-$ docker run --rm -it docker/ucp uninstall --help
-```
 
 To uninstall Docker UCP from a cluster, you should:
 
 1. Uninstall UCP from every node joined in the cluster,
 2. Uninstall UCP from every controller node, one at a time.
 
+When you install UCP, your Docker Engine is automatically configured for
+multi-host networking. When uninstalling, you need to delete or update the
+`/etc/docker/daemon.json` file and restart the Docker daemon on each node.
+
+
 ## Example
 
 In this example we’ll be running the uninstall command interactively, so that
@@ -74,5 +75,19 @@ You can also use flags to pass values to the uninstall command.
     Deleted: sha256:93743d5df2362466e2fe116a677ec6a4b0091bd09e889abfc9109047fcfcdebf
     ```
 
-4. Go to the UCP web application, and confirm the node was removed from the
+4. Delete the engine-discovery configuration
+
+    ```bash
+    $ sudo rm /etc/docker/daemon.json
+    ```
+
+5. Restart the Docker daemon
+
+    As an example, on a Ubuntu host
+
+    ```bash
+    $ sudo service docker restart
+    ```
+
+6. Go to the UCP web application, and confirm the node was removed from the
 cluster.

monitor/index.md

@@ -10,3 +10,11 @@ identifier="mn_monitor_ucp"
 weight=50
 +++
 <![end-metadata]-->
+
+# Monitor UCP
+
+This section includes the following topics:
+
+* [Monitor your cluster](monitor-ucp.md)
+* [Troubleshoot your cluster](troubleshoot-ucp.md)
+* [Troubleshoot cluster configurations](troubleshoot-configurations.md)

release_notes.md

@@ -12,6 +12,58 @@ weight=110
 
 # UCP Release Notes
 
+## Version 1.1.0
+
+**Features**
+
+* Core
+  * Added new commands to the docker/ucp image: backup, restore, id,
+  regen-certs, restart, stop
+  * UCP and DTR are now using a unified authentication service
+  * Users and teams created in UCP are displayed in DTR under the 'Datacenter'
+  organization
+  * When installing UCP, multi-host networking is Automatically configured
+  * All controllers joined to the cluster now have replicated CAs
+  * All UCP components were compiled the Go 1.5.4 and 1.6 to address Go security
+  vulnerabilities
+​
+* UI
+  * Now you can deploy apps from the UI using a docker-compse.yml file
+  * There's a new setting to prevent users from deploying containers to the UCP
+  controller nodes
+  * Improved usability of LDAP configuration settings
+  * Images page no longer shows the sha256 id of each image ID
+  * User profiles now display default permissions
+  * Improved feedback when creating users and teams with invalid characters
+  * Added horizontal scrollbar to wide pages
+
+**Bug Fixes**
+
+* Improved messages when installing UCP on a host with firewall rules
+* Images page no longer shows images generated from intermediate builds
+* Images page no longer hangs when pulling an image
+* Scaling a container from the UI now preserves parameters like 'net' and 'privileged'
+* Fixed `docker ps --filter` to filter containers correctly
+
+
+**Misc**
+
+* You no longer need to install UCP with --swarm-experimental to use swarm container rescheduling
+* All UCP containers now have the 'com.docker.ucp.version' label with their upstream version or UCP version
+* When running docker/ucp in interactive mode, the parameters and environment variables passed to the command are displayed
+* Renamed 'external-ucp-ca' flag to 'external-server-cert' for clarity. The first is deprecated but still available
+
+**Component Versions**
+
+UCP 1.1.0 uses:
+
+* cfssl 1.2.0
+* Docker Compose 1.7.0
+* Docker Swarm: 1.2.0
+* etcd 2.2.5
+* RethinkDB 2.3.0
+​
+
 ## Version 1.0.4
 
 **Security update**

user-management/index.md

@@ -9,3 +9,9 @@ parent="mn_ucp"
 weight=70
 +++
 <![end-metadata]-->
+
+# Manage users in UCP
+
+This section includes the following topics:
+
+* [Manage users](manage-users.md)