diff --git a/_data/toc.yaml b/_data/toc.yaml index dd3fd854c4..abd8b8564b 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -630,7 +630,9 @@ toc: - path: /ucp/overview/ title: Universal Control Plane overview - path: /ucp/install-sandbox/ - title: Evaluate UCP in a sandbox + title: Install DDC in a sandbox for evaluation + - path: /ucp/install-sandbox-2/ + title: Evaluate DDC in a sandbox deployment - path: /ucp/architecture/ title: Architecture - sectiontitle: Installation diff --git a/ucp/images/container_edit.png b/ucp/images/container_edit.png deleted file mode 100644 index d168849ef3..0000000000 Binary files a/ucp/images/container_edit.png and /dev/null differ diff --git a/ucp/images/controller-containers.png b/ucp/images/controller-containers.png deleted file mode 100644 index 16ed7cc837..0000000000 Binary files a/ucp/images/controller-containers.png and /dev/null differ diff --git a/ucp/images/dashboard.png b/ucp/images/dashboard.png deleted file mode 100644 index d4f790362f..0000000000 Binary files a/ucp/images/dashboard.png and /dev/null differ diff --git a/ucp/images/display_container.png b/ucp/images/display_container.png deleted file mode 100644 index a41b9624e3..0000000000 Binary files a/ucp/images/display_container.png and /dev/null differ diff --git a/ucp/images/get-license.png b/ucp/images/get-license.png deleted file mode 100644 index 90bae15a44..0000000000 Binary files a/ucp/images/get-license.png and /dev/null differ diff --git a/ucp/images/install-sandbox-1.png b/ucp/images/install-sandbox-1.png new file mode 100644 index 0000000000..9b3962a4a6 Binary files /dev/null and b/ucp/images/install-sandbox-1.png differ diff --git a/ucp/images/install-sandbox-2-1.png b/ucp/images/install-sandbox-2-1.png new file mode 100644 index 0000000000..7f4e27d5f8 Binary files /dev/null and b/ucp/images/install-sandbox-2-1.png differ diff --git a/ucp/images/install-sandbox-2-2.png b/ucp/images/install-sandbox-2-2.png new file mode 100644 index 0000000000..52d2be1d90 Binary files /dev/null and b/ucp/images/install-sandbox-2-2.png differ diff --git a/ucp/images/install-sandbox-2-3.png b/ucp/images/install-sandbox-2-3.png new file mode 100644 index 0000000000..ad24c32086 Binary files /dev/null and b/ucp/images/install-sandbox-2-3.png differ diff --git a/ucp/images/install-sandbox-2.png b/ucp/images/install-sandbox-2.png new file mode 100644 index 0000000000..3da450cb80 Binary files /dev/null and b/ucp/images/install-sandbox-2.png differ diff --git a/ucp/images/install-sandbox-3.png b/ucp/images/install-sandbox-3.png new file mode 100644 index 0000000000..9e82ff67a7 Binary files /dev/null and b/ucp/images/install-sandbox-3.png differ diff --git a/ucp/images/license.png b/ucp/images/license.png deleted file mode 100644 index 0324213717..0000000000 Binary files a/ucp/images/license.png and /dev/null differ diff --git a/ucp/images/port_config.png b/ucp/images/port_config.png deleted file mode 100644 index 5b6e3fea42..0000000000 Binary files a/ucp/images/port_config.png and /dev/null differ diff --git a/ucp/images/skip-this.png b/ucp/images/skip-this.png deleted file mode 100644 index f917ebcc92..0000000000 Binary files a/ucp/images/skip-this.png and /dev/null differ diff --git a/ucp/images/welcome_nginx.png b/ucp/images/welcome_nginx.png deleted file mode 100644 index 37a57ec484..0000000000 Binary files a/ucp/images/welcome_nginx.png and /dev/null differ diff --git a/ucp/install-sandbox-2.md b/ucp/install-sandbox-2.md new file mode 100644 index 0000000000..362788bf0a --- /dev/null +++ b/ucp/install-sandbox-2.md @@ -0,0 +1,281 @@ +--- +title: Evaluate DDC in a sandbox deployment +description: Learn how to push Docker images to your private registry and deploy them to your cluster. +keywords: "Docker Datacenter, registry, orchestration" +--- + +# Evaluate DDC in a sandbox deployment + +This tutorial assumes that you have +[installed and configured](install-sandbox.md) a two-node Docker Datacenter +installation including both UCP and DTR using the instructions +[here](install-sandbox.md). If you haven't done this, we can't promise that this +tutorial workflow will work exactly the same. + +In the second half of this tutorial, we'll walk you through a typical deployment +workflow using your sandbox installation of DDC as if it was a production +instance installed on your organization's network. + + +Over the course of this tutorial, we will: + +- Create a repository in DTR +- Set up certificates or set insecure flag +- Pull a Docker image, tag it and push it to your DTR repo. +- Edit the Docker image you just pulled, tag it and push it to your DTR repo. +- Set up your shell so you can interact with Docker objects in UCP using the command line +- Use UCP to deploy your edited image to a node + + +## Step 1: Set --insecure registry or set up DTR trust and login + +Next, we'll set up a security exception that allows a the Docker-machine hosts +used in your UCP cluster to push images to and pull images from DTR even though +the DTR instance has a self-signed certificate. For a production deployment, +you would +[set up certificate trust](https://docs.docker.com/ucp/configuration/dtr-integration/) +between UCP and DTR, and +[between DTR and your Docker Engine](https://docs.docker.com/docker-trusted-registry/repos-and-images/), +but for our sandbox deployment we can skip this. + +> **Warning**: These steps produce an insecure DTR connection. Do not use these +configuration steps for a production deployment. + +To allow the Docker Engine to connect to DTR despite it having a self-signed +certificate, we'll specify that there is one insecure registry that we'll allow +the Engine instance to connect to. We'll add this exception by editing the +configuration file where docker-machine stores the host's configuration details. + +1. Edit the file found at `~/.docker/machine/machines/node1/config.json` using +your preferred text editor. + + For example + + ```none + $ vi ~/.docker/machine/machines/node1/config.json + ``` + +2. Locate `InsecureRegistry` key in `EngineOptions` section, and add your DTR +instance's IP between the brackets, enclosed in quotes. + + For example + + ``` + "InsecureRegistry": ["192.168.99.101"], + ``` + +3. Save your changes to the file and exit. + +4. Run the command `docker-machine provision node1` to update `node1`'s +configuration with the new `InsecureRegistry` setting. + +5. Repeat this process for `node2`. + + Because UCP runs a `docker pull` from DTR for each node in its cluster, + you must make this security exception for all nodes in the cluster. + +This allows you to push docker images to, and pull docker images from, the +registry. + + +## Step 2: Create an image repository in DTR + +In this step, we'll create an image repository in DTR that you will be able to +push Docker images to. Remember a Docker image is a combination of code and +filesystem used as a template to create a container. + +1. In your web browser, go to the DTR web UI. + + If you need help finding the URL for this host, you can use + `docker-machine ls` to find the IP for `node2` where you installed DTR. + +2. Log in to DTR using your administrator credentials. + +3. Navigate to the **Repositories** screen and click **New Repository**. + +4. In the repository name field, enter `my-nginx`. + +5. Click **Save**. + +## Step 3: Pull an image, tag and push to DTR + +1. In your terminal, make sure `node1` is active using `docker-machine ls`. + + This is the node that you configured the security exception for, and if you + are connecting to a Docker Engine without this exception you won't be able + to push to your DTR instance. + + If necessary, use `docker-machine env` to make `node1` active. + + ```none + $ eval "$(docker-machine env node1)" + ``` + +2. Pull the latest Nginx image + + ``` + $ docker pull nginx:latest + ``` + + Because you aren't specifying a registry as part of the `pull` command, + Docker Engine locates and downloads the latest `nginx` image from Docker + Cloud's registry. + +3. Log in to your DTR instance on `node2` using the `docker login` command and +the DTR instance's IP address. + + ```none + docker login $(docker-machine ip node2) + ``` + + Enter your administrator username and password when prompted. + +4. Tag the `nginx` image you downloaded. + + Use the IP of your DTR instance to specify the repository path, and the . + + ```none + $ docker tag nginx:latest $(docker-machine ip node2)/admin/my-nginx:official + ``` + +5. Push the tagged image to your DTR instance. + + ```none + $ docker push $(docker-machine ip node2)/admin/my-nginx:official + ``` + +You now have a copy of the official Nginx Docker image available on your +sandbox DTR instance. + +## Step 4: Pull your image from DTR into UCP + +UCP does not automatically pull images from DTR. To make an image from DTR +appear in UCP, you'll use the UCP web UI to perform a `docker pull`. This `pull` +command pulls the image and makes it available on all nodes in the UCP cluster. + +1. From the UCP dashboard, click **Images** in the left navigation. + +2. Click **Pull Image**. + +3. Enter the full path to the image that you just pushed to your DTR instance. + + For the example path in this demo use `/admin/my-nginx:official` + +4. Click **Pull**. + + UCP contacts the DTR host, and pulls the image on each node in the cluster. + +## Step 5. Deploy a container from the UCP web interface + +UCP allows you to deploy and manage "Dockerized" applications in production. An +application is built using Docker objects, such as images and containers, and +Docker resources, such as volumes and networks. + +UCP deploys and manages these objects and resources using remote API calls to +the Engine daemons running on the nodes. For example, the `run` action may +deploy an image in a Docker container. That image might define a service such as +an Nginx web server or a database like Postgres. + +A UCP administrator initiates Engine actions using the UCP dashboard or the +Docker Engine CLI. In this step, you deploy a container from the UCP dashboard. +The container runs an Nginx server, so you'll need to launch the `nginx` image +inside of it. + +1. Log in to the UCP **Dashboard**. + +2. Click **Containers** from the left navigation. + + The system displays the **Containers** page. + + > **Tip**: UCP runs some containers that support its own operations called + "system" containers. These containers are hidden by default. + +3. Click **+ Deploy Container**. + + We'll deploy the simple `nginx` container you just pulled, using specific + values for each field. If you already know what you're doing, feel free to + explore once you've completed this example. + +4. Enter the path to the `nginx:official` image you just pulled in the +**image name** field. + + This should something like `/admin/my-nginx:official` + + An image is a specific build of software you want to run. The software might + be a stand-alone application, or component software necessary to support a + complex service. + +5. Enter `nginx_official` for the container name. + + This name just identifies the container on your network. + +6. Click **Network** to expand the networking settings. + + A Docker container is isolated from other processes on your network and has + its own internal network configuration. To access the service inside a + container, you need to expose the container's port, which maps to a port on + the node. The node is hosting an instance of Docker Engine, so its port is + called the **Host Port**. + +7. Enter `443` in the **Port** field and enter `4443` the **Host Port** field. + + We're mapping port 443 in the container to a different port on the host + because your UCP instance is already serving the web interface on port 443. + +8. Click the plus sign to add another **Port**. + +9. For this port, enter `80` in the **Port** field, and enter `8080` in the +**Host Port** field. + + When you are done, your dialog should look like this: + + ![Port configuration](images/install-sandbox-2-1.png) + +10. Click **Run Container** to deploy the container. + + +## Step 6. View a running service + +At this point, you have deployed a container and you should see the container +status is `running`. Recall that you deployed an Nginx web server. That server +comes with a default page that you can view to validate that the server is +running. In this step, you open the running server. + +1. Navigate back to the **Containers** page. + +2. Click the **nginx_official** container. + + ![](images/install-sandbox-2-2.png) + + The system displays the container's details and some operations you can run + on the container. + +3. Scroll down to the ports section. + + You'll see an IP address with port `8080` for the server. + +4. Copy the IP address to your browser and paste the information you copied. + + You should see the welcome message for nginx. + + ![](images/install-sandbox-2-3.png) + + +## Explore UCP + +At this point, you've completed the guided tour of a UCP installation. You've +learned how to create a UCP installation by creating two nodes and designating +one of them as a controller. You've pushed an image to Docker Trusted Registry +and used that image to run a container in the cluster managed by UCP. + +In a real UCP production installation, UCP admins and operators are expected to +do similar work every day. While the applications they launch will be more +complicated, the workflow will be very similar to what you've just learned. + +Take some time to explore UCP some more. Investigate the documentation for other +activities you can perform with UCP. + +## Where to go next + +* [UCP architecture](architecture.md) +* [UCP system requirements](installation/system-requirements.md) diff --git a/ucp/install-sandbox.md b/ucp/install-sandbox.md index aaeb34123f..8c71a0a432 100644 --- a/ucp/install-sandbox.md +++ b/ucp/install-sandbox.md @@ -1,157 +1,136 @@ --- aliases: - /ucp/evaluation-install/ -description: Evaluation installation -keywords: -- tbd, tbd -menu: - main: - identifier: ucp_evaluate_sandbox - parent: mn_ucp - weight: 10 -title: Evaluate UCP in a sandbox +title: Install DDC in a sandbox for evaluation +description: Learn how to get a 30-day trial of Docker Datacenter up and running. +keywords: "Docker Datacenter, orchestration, trial" --- -# Evaluate UCP in a sandbox +# Install DDC in a sandbox for evaluation -This page helps you to learn about Docker Universal Control Plane (UCP) at a -high-level through installing and running UCP in your local, sandbox -installation. The installation should be done on a Mac OS X or Windows system. -If you are experienced with Linux or a technical DevOps user wanting a technical -deep dive, please feel free to skip this evaluation and go directly to -[Plan a production installation](installation/plan-production-install.md) -and then to [Install UCP for production](installation/install-production.md). +This page introduces Docker Datacenter (also known as DDC): a combination of +Docker Universal Control Plane (UCP) and Docker Trusted Registry (DTR), and +walks you through installing it on a local (non-production) host or sandbox. +Once you've installed, we'll also give you a guided tour so you can evaluate its +features. -A UCP installation consists of an UCP controller and one or more hosts. These -instructions use Docker Machine, Docker's provisioning tool, to create several -local hosts running Docker Engine. Once you create these hosts, you'll install -UCP and its components on them just as you would in a full-on UCP installation. +The instructions here are for a sandbox installation on Mac OS X or Windows +systems. If you're an experienced Linux user, or if you want more detailed +technical information, you might want to skip this evaluation and go directly to +[Plan a production installation](installation/plan-production-install.md) and +then to [Install UCP for production](installation/install-production.md). ->**Note**: This evaluation installs UCP on top of the open source software version of -Docker Engine inside of a VirtualBox VM which is running the small-footprint -`boot2docker.iso` Linux. Such a configuration is **not** supported for UCP in -production. +> **Note**: This evaluation installs using the open source software version of +Docker Engine inside of a VirtualBox VM which runs the small-footprint +`boot2docker.iso` Linux. This configuration is **not** a production +configuration. +## Introduction: About this example -## Step 1. About this example +In this tutorial, we'll use Docker's provisioning tool - Docker Machine - to +create two virtual hosts. These two hosts are VirtualBox VMs running a small +footprint Linux image called `boot2docker.iso`, with the open source version of +Docker Engine installed. -This example introduces you to UCP by means of a very simple sandbox example. -You'll create a small UCP installation, deploy a container through UCP, and -examine the interface. +![Docker Machine setup](images/explain.png) -For this evaluation installation, you'll use Machine to create two VirtualBox -VMs. Each VM runs small foot-print Linux image called `boot2docker.iso`. Machine -provisions each VM with the open source Docker Engine. - -![Explain setup](images/explain.png) - -You'll use each of these VMs as a node in a simple UCP installation. The -installation will have a controller and a node. The installation rests on top of -a Docker Swarm cluster. The UCP installation process by default secures the cluster via self-signed TLS certificates. +A UCP installation consists of an UCP controller and one or more hosts. We'll +install UCP on one host, then join the second node to UCP as a swarm member. The +two VMs create a simple swarm cluster with one controller, which by default +secures the cluster via self-signed TLS certificates. ![Sandbox](images/sandbox.png) -This example is intended as an introduction for non-technical users wanting to -explore UCP for themselves. If you are a highly technical user intending to act as -UCP administration operator, you may prefer to skip this and go straight to -[Plan a production installation](installation/plan-production-install.md). +DDC's second component is DTR, which must be installed on a host that's a member +of the UCP swarm. So next, we'll then install DTR on that second node. ->**Note**: The command examples in this page were tested for a Mac OSX environment. -If you are in another, you may need to adjust to use analogous commands for your environment. +Once you've installed UCP and DTR you'll work through a tutorial to deploy a +container through UCP, and explore the user interface. -## Step 2. Verify the prerequisites +>**Note**: The command examples in this page were tested for a Mac OS X +environment. If you are in another, you may need to change the commands to use +the correct ones for you environment. + +## Prerequisites This example requires that you have: -* Docker Engine -* Docker Machine +* [Docker Toolbox installed](https://docs.docker.com/toolbox/overview/) +(contains Docker Machine and Docker Engine) +* A free Docker ID account -If you don't have those components, start by [installing them](/toolbox/overview.md). +## Step 1: Provision hosts with Engine -## Step 3. Provision hosts with Engine +In this step, you'll provision two VMs for your UCP sandbox installation. One +will run UCP and one will be used to run containers, so the host specifications +will be slightly different. -In this step, you provision two VMs for your UCP installation. This step is -purely to enable your evaluation. You would never run UCP in production on local -VMs with the open source Engine. - -In a production installation, you would use enterprise-grade Linux servers as -your nodes. These nodes could be on your company's private network or in the -cloud. UCP requires that each node be installed with the Commercially Supported -Docker Engine (CS Engine). +In a production environment you would use enterprise-grade hosts instead +of local VMs. These nodes could be on your company's private network or +in the cloud. You would also use the Commercially Supported (CS Engine) version +of Docker Engine required by UCP. Set up the nodes for your evaluation: 1. Open a terminal on your computer. -2. Use Docker Machine to list any VMs in VirtualBox. +2. Use Docker Machine to list any VMs in VirtualBox. - $ docker-machine ls - NAME ACTIVE DRIVER STATE URL SWARM - default * virtualbox Running tcp://192.168.99.100:2376 + ```none + $ docker-machine ls -3. Create a VM named `node1`. + NAME ACTIVE DRIVER STATE URL SWARM + default * virtualbox Running tcp://192.168.99.100:2376 + ``` - UCP runs best with a minimum of 1.50 GB in memory and requires a minimum of - 3.00 GB disk space. When you create your virtual host, you supply options to - size it appropriately. +3. Create a VM named `node1` using the following command. - $ docker-machine create -d virtualbox \ - --virtualbox-memory "2000" \ - --virtualbox-disk-size "5000" node1 - Running pre-create checks... - Creating machine... - (node1) Copying /Users/mary/.docker/machine/cache/boot2docker.iso to /Users/mary/.docker/machine/machines/node1/boot2docker.iso... - (node1) Creating VirtualBox VM... - (node1) Creating SSH key... - (node1) Starting the VM... - (node1) Waiting for an IP... - Waiting for machine to be running, this may take a few minutes... - Machine is running, waiting for SSH to be available... - Detecting operating system of created instance... - Detecting the provisioner... - Provisioning with boot2docker... - Copying certs to the local machine directory... - Copying certs to the remote machine... - Setting Docker configuration on the remote daemon... - Checking connection to Docker... - Docker is up and running! - To see how to connect Docker to this machine, run: docker-machine env node1 + ```none + $ docker-machine create -d virtualbox \ + --virtualbox-memory "2500" \ + --virtualbox-disk-size "5000" node1 + ``` -4. Create a VM named `node2`. + When you create your virtual host you specify the memory and disk size + options. UCP requires a minimum of 3.00 GB disk space and runs best with a + minimum of 2 GB of memory. - $ docker-machine create -d virtualbox \ - --virtualbox-memory "2000" node2 +4. Create a VM named `node2` using the command below. -5. Use the Machine `ls` command to list your hosts. + ```none + $ docker-machine create -d virtualbox \ + --virtualbox-memory "2500" \ + --virtualbox-disk-size "5000" node2 + ``` - NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS - node1 - virtualbox Running tcp://192.168.99.104:2376 v1.10.0 - node2 - virtualbox Running tcp://192.168.99.102:2376 v1.10.0 +5. Use the `docker-machine ls` command to list your hosts. - At this point, all the nodes are in the `Running` state. You have your hosts provisioned, now you are ready to install UCP itself. + ```none + $ docker-machine ls -## Step 4. Learn about the ucp tool + NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS + default - virtualbox Stopped Unknown + node1 - virtualbox Running tcp://192.168.99.100:2376 v1.12.1 + node2 - virtualbox Running tcp://192.168.99.101:2376 v1.12.1 + ``` + At this point, both nodes are in the `Running` state and ready for UCP installation. -You install UCP by using the Engine CLI to run the `ucp` tool. The `ucp` tool is -an image with subcommands to `install` a UCP controller or `join` a node to a -UCP controller. The general format of these commands are: +## About the ucp tool +To install UCP, you'll use the Docker CLI to pull and run the `docker/ucp` +image, which contains a bootstrapper tool, which is designed to make UCP easier +to install than many enterprise-grade applications. The `ucp` tool runs +`docker run` commands to `install` a UCP controller or `join` a node to a UCP +controller. -| Docker client | `run` command with options | `ucp` image | Subcommand with options | -|:--------------|:---------------------------|:-------------|:------------------------| -| `docker` | `run --rm -it` | `docker/ucp` | `install --help` | -| `docker` | `run --rm -it` | `docker/ucp` | `join --help` | -| `docker` | `run --rm -it` | `docker/ucp` | `uninstall --help` | - -You can use these subcommands interactively by passing them the `-i` option or by -passing command-line options. The `ucp` tool is designed to make UCP easier to -install than many enterprise-grade applications. In interactive mode the tool -works to discover your network topology and suggest default answers to you. This -evaluation uses the interactive method. +The general format of these commands are a `docker run --rm -it docker/ucp` with +one or more subcommands, and you'll find them later in this document. For the +tutorial purposes, we use the `-i` options for "interactive" install mode, but +you can run them unattended in production. Regardless of how you use the `docker/ucp` tool, the default install supplies -some quick default options for both data volumes and the certificate authority -(CA). In a production installation you can optionally: +default options for both data volumes and the certificate authority (CA). In a +production installation you can also optionally: * use the high availability feature * customize the port used by the UCP web application @@ -159,535 +138,212 @@ some quick default options for both data volumes and the certificate authority * create your own data volumes * use your own TLS certificates -You'll learn more about these when you Plan -a production installation. For now, in this evaluation sandbox installation, -you'll use all the default values with one exception, you'll specify a custom -port for the Swarm manager. +You can learn more about these when you +[plan a production installation](installation/plan-production-install.md). -## Step 5. Install the UCP controller +## Step 2. Install the UCP controller In this step, you install the UCP controller on the `node1` you provisioned earlier. A controller serves the UCP application and runs the processes that manage an installation's Docker objects. -In a production installation, a system administrator can implement -UCP's high availability feature. High availability allows you to designate -several nodes as controller replicas. In this way, if one controller fails -a replica node is ready to take its place. +In a production installation, a system administrator can set up UCP's high +availability feature, which allows you to designate several nodes as controller +replicas. This way if one controller fails, a replica node is ready to take its +place. -For this evaluation, you won't need that level of robustness. A single -host for the controller suffices. +For this sandbox installation, we don't need high availability, so a single +host for the controller works fine. -1. If you don't already have one, open a terminal on your computer. +1. Open a terminal on your computer if you don't have one open already. 2. Connect the terminal environment to the `node1` you created. - a. Use `docker-machine env` command to get the settings. + a. Use the `docker-machine env` command to get the settings. - $ docker-machine env node1 - export DOCKER_TLS_VERIFY="1" - export DOCKER_HOST="tcp://192.168.99.103:2376" - export DOCKER_CERT_PATH="/Users/mary/.docker/machine/machines/node1" - export DOCKER_MACHINE_NAME="node1" - # Run this command to configure your shell: - # eval $(docker-machine env node1) + ```none + $ docker-machine env node1 - b. Run the `eval` command to set your environment. + export DOCKER_TLS_VERIFY="1" + export DOCKER_HOST="tcp://192.168.99.100:2376" + export DOCKER_CERT_PATH="/Users/ldr/.docker/machine/machines/node1" + export DOCKER_MACHINE_NAME="node1" + # Run this command to configure your shell: + # eval $(docker-machine env node1) + ``` - $ eval $(docker-machine env node1) + b. Run the `eval` command found in the final line to set your environment. - c. Verify that `node1` has an active environment. + ```` + $ eval $(docker-machine env node1) + ```` - $ docker-machine ls - NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS - node1 * virtualbox Running tcp://192.168.99.104:2376 v1.10.0 - node2 - virtualbox Running tcp://192.168.99.102:2376 v1.10.0 + Running this `eval` command sends the `docker` commands in the following + steps to the Docker Engine on on `node1`. - An `*` (asterisk) in the `ACTIVE` field indicates that the `node1` environment is active. + c. Verify that `node1` is the active environment. - The client will send the `docker` commands in the following steps to the Docker Engine on `node1`. + You can do this by running `docker-machine ls` and checking that there is + an `*` (asterisk) in the `ACTIVE` field next to `node1`. -3. Start the `ucp` tool to install interactively. +3. Start the `ucp` tool to install interactively. - >**Note**: If you are on a Windows system, your shell can't resolve the - `$(docker-machine ip node2)` variable. So, replace it with the actual IP - address. + ```none + $ docker run --rm -it \ + -v /var/run/docker.sock:/var/run/docker.sock \ + --name ucp docker/ucp install -i \ + --swarm-port 3376 --host-address $(docker-machine ip node1) + ``` - $ docker run --rm -it \ - -v /var/run/docker.sock:/var/run/docker.sock \ - --name ucp docker/ucp install -i \ - --swarm-port 3376 --host-address $(docker-machine ip node1) - Unable to find image 'docker/ucp:latest' locally - latest: Pulling from docker/ucp - 0198ad4008dc: Pull complete - 291084ae72f3: Pull complete - Digest: sha256:28b6c9640e5af0caf2b2acbbbfd7c07bdbec6b170f04cbaeea7bb4909d74898d - INFO[0000] Verifying your system is compatible with UCP + > **Note**: If you are on a Windows system, your shell won't be able to + resolve the `$(docker-machine ip node1)` variable. Instead, edit the command + supplied to replace it with the actual IP address. - The first time you run the `ucp` tool, the `docker run` command pulls its - image from the Docker Hub. The image contains the `ucp` tool. The tool - downloads if needed and then verifies your system supports UCP. The tool is - designed to discover the information it needs if it can. This reduces the - change for human error or mistakes during the install. + The first time you run the `ucp` tool, the `docker run` command pulls the + UCP bootstrapper image from Docker Cloud. The tool downloads the packages it + needs, and verifies that your system will support a UCP installation. -4. Enter a UCP password when prompted and then confirm it. +4. Enter a password for UCP when prompted, and then confirm it. - Please choose your initial UCP admin password: - Confirm your initial password: - INFO[0016] Pulling required images... (this may take a while) + The system prompts you for Subject alternative names (SANs). In this + sandbox, you've already provided the IP address and the `ucp` tool + discovered this for you and shows it in the controller list. - The UCP system relies on a set of Docker images running in containers. The `ucp` installer gets the latest official UCP images. +5. Press enter to proceed using the list the `ucp` tool provided. - The system prompts you for Subject alternative names (SANs). UCP requires - that all clients, including the Docker Engine, use a Swarm TLS certificate - chain signed by the UCP Swarm Root CA. You can provide the certificate - system with subject alternative names or SANs. The SANs are used to set up - individual "leaf certificates." In this sandbox, you've already provided the IP address and the `ucp` tool discovered this for you and shows it in the controller list. + UCP requires that all clients, including the Docker Engine, use a Swarm TLS + certificate chain signed by the UCP Swarm Root CA. You can provide the + certificate system with subject alternative names or SANs, which allow you + to set up individual "leaf certificates." - WARN[0004] None of the hostnames we'll be using in the UCP certificates - [controller 127.0.0.1 172.17.0.1 192.168.99.106] contain a domain - component. Your generated certs may fail TLS validation unless you only - use one of these shortnames or IPs to connect. You can use the --san - flag to add more aliases + When it completes, the `ucp` tool prompts you to log in into the UCP web + interface and gives you its location. You'll do this in the next step so + you can install a license. - You may enter additional aliases (SANs) now or press enter to proceed - with the above list. - Additional aliases: +## Step 3. License your installation -5. Press enter to proceed with the list the `ucp` tool provides. +In this step, you'll get a license, log in to the UCP web interface and install +the license. Docker allows you to run an evaluation version of UCP with a single +controller and node for up to 30 days. - INFO[0005] Installing UCP with host address 192.168.99.106 - If this is - incorrect, please specify an alternative address with the - '--host-address' flag - WARN[0000] None of the hostnames we'll be using in the UCP certificates - [controller 127.0.0.1 172.17.0.1 192.168.99.106 192.168.99.106] contain - a domain component. Your generated certs may fail TLS validation unless - you only use one of these shortnames or IPs to connect. You can use the - --san flag to add more aliases - INFO[0001] Generating Swarm Root CA - INFO[0022] Generating UCP Root CA - INFO[0024] Deploying UCP Containers - INFO[0028] UCP instance ID: CJQN:ZQVX:B6CC:KFD3:IXN5:FGLF:GXMN:WALD:QFHU:QLSX:ZCBY:CAL7 - INFO[0028] UCP Server SSL: SHA1 Fingerprint=02:36:16:93:B4:21:B7:AD:0A:6C:0F:3C:99:75:18:5D:5A:F7:C4:0C - INFO[0028] Login as "admin"/(your admin password) to UCP at https://192.168.99.106:443 +[Learn how to get a trial license](installation/license.md). - When it completes, the `ucp` tool prompts you to login into the UCP GUI - by giving you its location. You'll do this and install a license in Step 6, - below. +In your terminal window you should have instructions on how to access the UCP +web UI. It should look like this: +```none +INFO[0056] Login as "admin"/(your admin password) to UCP at https://192.168.99.100:443 +``` -## Step 6. License your installation +In your browser navigate to that IP address, and upload your trial license. -In this step, you log into UCP, get a license, and install it. Docker allows you to run an evaluation version of UCP with a single controller and node for up to 30 days. +![](images/install-sandbox-1.png) -1. Enter the address into your browser to view the UCP login screen. +## Step 4. Join a node - Your browser may warn you about the connection. The warning appears because, - in this evaluation installation, the UCP certificate was issued by a - built-in certificate authority (CA). Your actions with the install actually - created the certificate. If you are concerned, the certificate's fingerprint - is displayed during install and you can compare it. - -2. Click the **Advanced** link and then the **Proceed to** link. - - The login screen displays. - - ![](images/login-ani.gif) - -5. Enter `admin` for the username along with the password you provided to the `install`. - - After you enter the correct credentials, the UCP dashboard prompts for a - license. - - ![](images/skip-this.png) - -6. Press *Skip for now* to continue to the dashboard. - - ![](images/dashboard.png) - - The dashboard shows a single node, your controller node. It also shows you a - banner saying that you need a license. - -6. Follow the link on the UCP **Dashboard** to the Docker website to get a trial license. - - You must fill out a short form. After you complete the form, you are prompted with some **Installation Steps**. - -7. Press **Next** until you reach the **Add License** step. - - ![](images/get-license.png) - -8. Press the **Download License** button. - - Your browser downloads a `docker_subscription.lic` file. - -9. Save the file to a safe location. - -10. Return to the UCP Dashboard. - -11. Choose **Settings** from the "hamburger" menu on the left side. - - As you move through UCP, the header changes to display the appropriate - breadcrumbs. In this case you are on the **Dashboard/Settings*** page. - -12. Scroll down to the **License** section and click **Choose File**. - - Locate and upload your file. - - ![](images/license.png) - - Once you upload the file, the license message disappears from UCP. - -Take a minute and explore UCP. At this point, you have a single controller -running. How many nodes is that? What makes a controller is the containers it -runs. Locate the Containers page and show the system containers on your -controller. You'll know you've succeeded if you see this list: - -![](images/controller-containers.png) - -The containers reflect the architecture of UCP. The containers are running -Swarm, a key-value store process, and some containers with certificate volumes. -Explore the other resources. - -## Step 7. Join a node - -In this step, you join your UCP `node2` to the controller using the `ucp join` -subcommand. In a UCP production installation, you'd do this step for each node +In this step, you join your `node2` to the controller using the `ucp join` +command. In a production installation, you'd do this step for each node you want to add. -1. If you don't already have one, open a terminal on your computer. +1. Open a terminal on your computer if you don't already have one open. 2. Connect the terminal environment to the `node2` you provisioned earlier. - a. Use `docker-machine env` command to get the settings. + 1. Use `docker-machine env` command to get the settings command for `node2`. - $ docker-machine env node2 - export DOCKER_TLS_VERIFY="1" - export DOCKER_HOST="tcp://192.168.99.104:2376" - export DOCKER_CERT_PATH="/Users/mary/.docker/machine/machines/node2" - export DOCKER_MACHINE_NAME="node2" - # Run this command to configure your shell: - # eval $(docker-machine env node2) + ```none + $ docker-machine env node2 - b. Run the `eval` command to set your environment. + export DOCKER_TLS_VERIFY="1" + export DOCKER_HOST="tcp://192.168.99.101:2376" + export DOCKER_CERT_PATH="/Users/ldr/.docker/machine/machines/node2" + export DOCKER_MACHINE_NAME="node2" + # Run this command to configure your shell: + # eval $(docker-machine env node2) + ``` - $ eval $(docker-machine env node2) + b. Run the `eval` command to set your environment. - The client will send the `docker` commands in the following steps to the Docker Engine on on `controller`. + ``` + $ eval $(docker-machine env node2) + ``` -2. Run the `docker/ucp join` command. + Running this `eval` command sends the `docker` commands in the following + steps to the Docker Engine on `node2`. - >**Note**: If you are on a Windows system, your shell can't resolve the - `$(docker-machine ip node2)` variable. So, replace it with the actual IP - address. +3. Run the `docker/ucp join` command. - $ docker run --rm -it \ - -v /var/run/docker.sock:/var/run/docker.sock \ - --name ucp docker/ucp join -i \ - --host-address $(docker-machine ip node2) + > **Note**: If you are on a Windows system, your shell won't be able to + resolve the `$(docker-machine ip node2)` variable. Instead, edit the command + supplied to replace it with the actual IP address. - The `join` pulls several images and prompts you for the URL of the UCP Server. + ```none + $ docker run --rm -it \ + -v /var/run/docker.sock:/var/run/docker.sock \ + --name ucp docker/ucp join -i \ + --host-address $(docker-machine ip node2) + ``` - Unable to find image 'docker/ucp:latest' locally - latest: Pulling from docker/ucp - 0198ad4008dc: Pull complete - 291084ae72f3: Pull complete - Digest: sha256:28b6c9640e5af0caf2b2acbbbfd7c07bdbec6b170f04cbaeea7bb4909d74898d - Status: Downloaded newer image for docker/ucp:latest - Please enter the URL to your UCP Server: + The `join` command pulls several images, then prompts you for the URL of the + UCP Server. -3. Enter the URL of your server to continue. +4. Enter the URL of the UCP server to continue. - Orca server https://192.168.99.106 - Subject: ucp - Issuer: UCP Root CA - SHA1 Fingerprint=02:36:16:93:B4:21:B7:AD:0A:6C:0F:3C:99:75:18:5D:5A:F7:C4:0C - Do you want to trust this server and proceed with the join? (y/n): +5. Press `y` when prompted to continue and join the node to the swarm. - The system prompts you to join the server. +6. Enter the admin username and password for the UCP server when prompted. -4. Press `y` to continue and the tool prompts you for the username and password for your UCP server. + The installer continues and prompts you for SANs. In this sandbox, you've + already provided the IP address and the `ucp` tool discovered this for you + and shows it in the controller list. - Please enter your UCP Admin username: admin - Please enter your UCP Admin password: - INFO[0027] Pulling required images... (this may take a while) - WARN[0070] None of the hostnames we'll be using in the UCP certificates [node1 127.0.0.1 172.17.0.1 192.168.99.108] contain a domain component. Your generated certs may fail TLS validation unless you only use one of these shortnames or IPs to connect. You can use the --san flag to add more aliases - You may enter additional aliases (SANs) now or press enter to proceed with the above list. - Additional aliases: +7. Press `enter` to proceed without providing a SAN. - The system continues and prompts you for SANs. In this sandbox, you've already provided the IP address and the `ucp` tool discovered this for you and shows it in the controller list. + The installation is complete when you see the message + `Starting local swarm containers`. -5. Press enter to proceed without providing a SAN. +8. Log in to UCP with your browser and confirm that the new node appears. - WARN[0000] None of the hostnames we'll be using in the UCP certificates - [node1 127.0.0.1 172.17.0.1 192.168.99.108 192.168.99.108] contain a - domain component. Your generated certs may fail TLS validation unless you - only use one of these shortnames or IPs to connect. You can use the --san - flag to add more aliases - INFO[0000] This engine will join UCP and advertise itself with host - address 192.168.99.108 - If this is incorrect, please specify an - alternative address with the '--host-address' flag - INFO[0000] Verifying your system is compatible with UCP - INFO[0011] Starting local swarm containers ’ + ![](images/install-sandbox-2.png) -4. Login into UCP with your browser and check to make sure your new node appears. - The page should display your new node. +## Step 5: Install Docker Trusted Registry - ![](images/nodes.png) +Next, we'll install Docker Trusted Registry (DTR). DTR provides a secure +location to store your organization's Docker images. Images are used by UCP to +run containers that make up a service. By providing a secure connection between +DTR and UCP, you can verify that your production services contain only signed +code produced by your own organization. -## Step 8. Deploy a container +1. First, make sure you know the IP addresses of both your UCP and DTR nodes. +You can find this easily by running `docker-machine ls`. -UCP allows you to deploy and manage "Dockerized" applications in production. An -application is built up using Docker objects, such as images and containers, and -Docker resources, such as volumes and networks. +2. Run the `docker-machine env node2` command to make sure that you are passing +commands to the node on which you will install DTR. -UCP deploys and manages these objects and resources using remote API calls the -Engine daemons running on the nodes. For example, the `run` action may deploy an -image in a Docker container. That image might define a service such as an Nginix -web server or a database like Postgres. +3. Next, use the following command to install DTR on `node2`. -A UCP operator initiates Engine actions through the UCP dashboard or through the -Docker Engine CLI. In this step, you deploy a container through the UCP -dashboard. The container will run an Nginx server, so you'll need to launch the -`nginx` image inside of it. + ```none + $ docker run -it --rm docker/dtr install \ + --ucp-url $(docker-machine ip node1) \ + --ucp-insecure-tls \ + --ucp-node node2 \ + --dtr-external-url $(docker-machine ip node2) + ``` -1. Log into the UCP **Dashboard**. + You'll be prompted for the credentials of the UCP administrator. -2. Click **Containers**. +4. Verify that DTR is running by navigating your browser to the DTR server's IP. - The system displays the **Containers** page. UCP runs some containers that - support its own operations. These are called "system" containers and they - are hidden by default. +5. Confirm that you can log in using your UCP administrator credentials. -3. Click **+ Deploy Container**. +![](images/install-sandbox-3.png) - The system displays a dialog with several fields. Using the dialog requires some basic knowledge of Docker objects and their attributes. A UCP admin or operator would typically have this knowledge. For now, you'll just follow along. +**Congratulations!** You now have a working installation of Docker Datacenter +running in your sandbox. You can explore on your own, or continue your +evaluation by walking through our [guided tour](install-sandbox-2.md). -4. Enter `nginx` for the image name. - - An image is simply predefined software you want to run. The software might - be an actual standalone application or maybe some component software necessary - to support a complex service. - -5. Enter `nginx_server` for the container name. - - This name just identifies the container on your network. - -6. Click **Publish Ports** from the **Overview** menu. - - A Docker container, like it sounds, is securely isolated from other processes on your network. In fact, the container has its own internal network configuration. If you want to access to a service inside a container, you need to expose a container's port. This container port maps to a port on the node. The node is hosting an instance of Docker Engine, so its port is called the **Host Port**. - -7. Enter `443` in the **Port** and in the **Host Port** field. - -8. Use the plus sign to add another **Port**. - -9. For this port, enter `80` in the **Port** and **Host Port** field. - - When you are done, your dialog looks like the following: - - ![Port configuration](images/port_config.png) - -10. Click **Run Container** to deploy your container. - - ![Deployed](images/display_container.png) - -## Step 9. View a running service - -At this point, you have deployed a container and you should see the application running. Recall that you deployed an Nginx web server. That server comes with a default page. In this step, you open the running server. - -1. Make sure you are still on the **Containers** page. - -2. Select the edit icon on the container. - - ![Edit](images/container_edit.png) - - The system displays the container's details and some operations you can run on the container. - -3. Scroll down to the ports section. - - You'll see an IP address with port `80` for the server. - -4. Copy the IP address to your browser and paste the information you copied. - - You should see the welcome message for nginx. - - ![Port 80](images/welcome_nginx.png) - - -## Step 10. Download a client bundle - -In this step, you download the *client bundle*. Each node in your UCP cluster is running Engine. A UCP operator can use the Engine CLI client instead of UCP to interact with the Docker objects and resources UCP manages. To issue commands to a UCP node, your local shell environment must be configured with the same security certificates as the UCP application itself. The client bundle contains the certificates and a script to configure a shell environment. - -Download the bundle and configure your environment. - -1. If you haven't already done so, log into UCP. - -2. Choose **admin > Profile** from the right-hand menu. - - Any user can download their certificates. So, if you were logged in under a user name such as `davey` the path to download bundle is **davey > Profile**. Since you are logged in as `admin`, the path is `admin`. - -3. Click **Create Client Bundle**. - - The browser downloads the `ucp-bundle-admin.zip` file. - -4. Open a new shell on your local machine. - -5. Make sure your shell is does not have an active Docker Machine host. - - $ docker-machine ls - NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS - moxie - virtualbox Stopped Unknown - test - virtualbox Running tcp://192.168.99.100:2376 v1.10.1 - - While Machine has a stopped and running host, neither is active in the shell. You know this because neither host shows an * (asterisk) indicating the shell is configured. - -4. Create a directory to hold the deploy information. - - $ mkdir deploy-app - -4. Navigate to where the bundle was downloaded, and unzip the client bundle - - $ unzip ucp-bundle.zip - Archive: ucp-bundle-admin.zip - extracting: ca.pem - extracting: cert.pem - extracting: key.pem - extracting: cert.pub - extracting: env.sh - extracting: env.ps1 - extracting: env.cmd - - -5. Change into the directory that was created when the bundle was unzipped - -6. Execute the `env.sh` script to set the appropriate environment variables for your UCP deployment. - - $ source env.sh - - Or if you are on Windows. - - $ source env.cmd - -7. Run `docker info` to examine the UCP deployment. - - Your output should show that you are managing UCP vs. a single node. - - $ docker info - Containers: 12 - Running: 0 - Paused: 0 - Stopped: 0 - Images: 17 - Role: primary - Strategy: spread - Filters: health, port, dependency, affinity, constraint - Nodes: 2 - node1: 192.168.99.106:12376 - └ Status: Healthy - └ Containers: 9 - └ Reserved CPUs: 0 / 1 - └ Reserved Memory: 0 B / 3.01 GiB - └ Labels: executiondriver=native-0.2, kernelversion=4.1.17-boot2docker, operatingsystem=Boot2Docker 1.10.0 (TCL 6.4.1); master : b09ed60 - Thu Feb 4 20:16:08 UTC 2016, provider=virtualbox, storagedriver=aufs - └ Error: (none) - └ UpdatedAt: 2016-02-09T12:03:16Z - node2: 192.168.99.107:12376 - └ Status: Healthy - └ Containers: 3 - └ Reserved CPUs: 0 / 1 - └ Reserved Memory: 0 B / 4.956 GiB - └ Labels: executiondriver=native-0.2, kernelversion=4.1.17-boot2docker, operatingsystem=Boot2Docker 1.10.0 (TCL 6.4.1); master : b09ed60 - Thu Feb 4 20:16:08 UTC 2016, provider=virtualbox, storagedriver=aufs - └ Error: (none) - └ UpdatedAt: 2016-02-09T12:03:11Z - Cluster Managers: 1 - 192.168.99.106: Healthy - └ Orca Controller: https://192.168.99.106:443 - └ Swarm Manager: tcp://192.168.99.106:3376 - └ KV: etcd://192.168.99.106:12379 - Plugins: - Volume: - Network: - CPUs: 2 - Total Memory: 7.966 GiB - Name: ucp-controller-node1 - ID: P5QI:ZFCX:ELZ6:RX2F:ADCT:SJ7X:LAMQ:AA4L:ZWGR:IA5V:CXDE:FTT2 - WARNING: No oom kill disable support - WARNING: No cpu cfs quota support - WARNING: No cpu cfs period support - WARNING: No cpu shares support - WARNING: No cpuset support - Labels: - com.docker.ucp.license_key=p3vPAznHhbitGG_KM36NvCWDiDDEU7aP_Y9z4i7V4DNb - com.docker.ucp.license_max_engines=1 - com.docker.ucp.license_expires=2016-11-11 00:53:53 +0000 UTC - -## Step 11. Deploy with the CLI - -In this exercise, you'll launch another Nginx container. Only this time, you'll use the Engine CLI. Then, you'll look at the result in the UCP dashboard. - -1. Connect the terminal environment to the `node2`. - - $ eval "$(docker-machine env node2)" - -2. Change to your user `$HOME` directory. - - $ cd $HOME - -2. Make a `site` directory. - - $ mkdir site - -3. Change into the `site` directory. - - $ cd site - -4. Create an `index.html` file. - - $ echo "my new site" > index.html - -5. Start a new `nginx` container and replace the `html` folder with your `site` directory. - - $ docker run -d -P -v $HOME/site:/usr/share/nginx/html --name mysite nginx - - This command runs an `nginx` image in a container called `mysite`. The `-P` tells the Engine to expose all the ports on the container. - -6. Open the UCP dashboard in your browser. - -7. Navigate to the **Containers** page and locate your `mysite` container. - - ![mysite](images/second_node.png) - -8. Scroll down to the ports section. - - You'll see an IP address with port `80/tcp` for the server. This time, you'll - find that the port mapped on this container than the one created yourself. - That's because the command didn't explicitly map a port, so the Engine chose - mapped the default Nginx port `80` inside the container to an arbitrary port - on the node. - -4. Copy the IP address to your browser and paste the information you copied. - - You should see your `index.html` file display instead of the standard Nginx welcome. - - ![mysite](images/second_node.png) - -## Explore UCP - -At this point, you've completed the guided tour of a UCP installation. You've -learned how to create a UCP installation by creating two nodes and designating -one of them as a controller. You've created a container running a simple web -server both using UCP and directly on the command line. You used UCP to get -information about what you created. - -In a real UCP production installation, UCP admins and operators are expected to -do similar work every day. While the applications they launch will be more -complicated, the interaction channels a user can take, the GUI or the -certificate bundle plus a command line, remain the same. - -Take some time to explore UCP some more. Investigate the documentation for other -activities you can perform with UCP. - -## Where to Go Next +## Where to go next +* [DDC guided tour](install-sandbox-2.md) * [UCP architecture](architecture.md) -* [UCP system requirements](installation/system-requirements.md)