In this quickstart, you'll learn how to deploy multi-container applications

with UCP.

While UCP is intended for deploying multi-container applications, the workflow

for developing them begins outside of the UCP installation. This page explains

the recommended workflow for developing applications. Then, it shows you

step-by-step how to deploy the fully developed application.

UCP is at the end of the application development workflow. You should only

deploy, or allowed to be deployed, individual containers or multi-container

applications that have been systematically developed and tested.

Your development team should develop in a local environment using the Docker

open source software (OSS) components. These components include:

* Docker Engine

* Docker Machine (if development is on Mac or Windows)

* Docker Swarm

* Docker Compose

* Docker Hub (for publicly available images)

Developing an application can include using public images from Docker Hub and

developing new custom images. If there are multiple containers involved, the

team should configure and test container port configurations. For applications

that require them, the team may need to create Docker container volumes and

ensure they are of sufficient size.

locally at scale on a Swarm cluster.

The output of application development should be a Docker Compose file and a set

of images ready for deployment. These images can be stored in Docker Hub. If

your company is using Docker Trusted Registry, the team may want to or be

required to store their application images in the company registry. The team

must ensure store the images in an accessible registry account.

This example requires that you have UCP deployed.

When deploying an application to UCP, you work from a local environment using

the UCP client bundle for your UCP user. You should never deploy from the

command-line while directly logged into a UCP node. The deploy on this page,

requires that your local environment includes the following software:

* Docker Engine

* Docker Compose

* Git

In this step, you download the *client bundle*. 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 shell on your local terminal.

5. If you are on Mac or Windows, ensure your shell does not have an active Docker Machine VM.

$ 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.

6. Create a directory to hold the deploy information.

$ mkdir deploy-app

7. Inside of a `deploy-app` create a directory to hold your UCP bundle files.

$ mkdir deploy-app/bundle

8. Change into the `deploy-app/bundle` directory and move the downloaded bundle into it.

$ cd deploy-app/bundle

$ mv ~/Downloads/ucp-bundle-admin.zip .

9. Unzip the client bundle.

$ unzip bundle.zip

Archive: bundle.zip

extracting: ca.pem

extracting: cert.pem

extracting: key.pem

extracting: cert.pub

extracting: env.sh

10. Change into the directory that was created when the bundle was unzipped

11. Execute the `env.sh` script to set the appropriate environment variables for your UCP deployment

$ source env.sh

12. Verify that you are connected to UCP by using the `docker info` command.

$ docker info

Containers: 11

Running: 11

Paused: 0

Stopped: 0

Images: 22

... <output snipped>

Plugins:

Volume:

Network:

Kernel Version: 4.2.0-23-generic

Operating System: linux

Architecture: amd64

CPUs: 3

Total Memory: 11.58 GiB

Name: ucp-controller-ucpdemo-0

ID: DYZQ:I5RM:VM6K:MUFZ:JXCU:H45Y:SFU4:CBPS:OMXC:LQ3S:L2HQ:VEWW

Labels:

com.docker.ucp.license_key=QMb9Ux2PKj-IshswTScxsd19n-c8LwtP-pQiDWy2nVtg

com.docker.ucp.license_max_engines=10

com.docker.ucp.license_expires=2016-05-03 19:52:02 +0000 UTC

The application you'll be deploying is a voting application. The voting

application is a dockerized microservice application. It uses a parallel web

frontend that sends jobs to asynchronous background workers. The application's

design can accommodate arbitrarily large scale. The diagram below shows the high

level architecture of the application.

The application is fully dockerized with all services running inside of

containers.

The frontend consists of an Interlock load balancer with *n* frontend web

servers and associated queues. The load balancer can handle an arbitrary number

of web containers behind it (`frontend01`- `frontendN`). The web containers run

a simple Python Flask application. Each web container accepts votes and queues

them to a Redis container on the same node. Each web container and Redis queue

pair operates independently.

The load balancer together with the independent pairs allows the entire

application to scale to an arbitrary size as needed to meet demand.

Behind the frontend is a worker tier which runs on separate nodes. This tier:

* scans the Redis containers

* dequeues votes

* deduplicates votes to prevent double voting

* commits the results to a Postgres container running on a separate node

Just like the front end, the worker tier can also scale arbitrarily.

When deploying in UCP, you won't need this exact architecture. For example, you

won't need the Interlock load balancer. Part of the work of UCP administrator

may be to polish the application the team created, leaving only what's needed for UCP.

For example, the team fully <a

href="https://github.com/docker/swarm-microservice-demo-v1" target="_blank">

developed and tested through a local environment using the open source Docker

ecosystem</a>. The Docker Compose file they created looks like this:

In this `docker-compose.file` includes a `build` command. You should never

`build` an image against the UCP controller or its nodes. You can find out if

the team built and stored the images described in the file, or you can build the

images yourself and push them to a registry. After a little work you could come

up with a `docker-compose.yml` that looks like this:

This revised compose file uses a set of images stored in Docker Hub. They happen

to be in Docker repositories because the sample application was built by a

Docker team. Compose allows you to designate a network and it defaults to

creating an `overlay` network. So, you can specify which networks in UCP to run

on. In this case, you won't manually create the networks, you'll let Compose create

the network for you.

In this step, you deploy the application in UCP.

1. Bring up the shell you configured in the [Step

2](#step-2-get-the-client-bundle-and-configure-a-shell).

2. Clone the sample compose file onto your local machine..

$ git clone https://github.com/nicolaka/voteapp-base.git

4. Change into the `voteapp-base` directory.

$ cd voteapp-base

6. Deploy the application.

$ docker-compose up

Creating network "voteappbase_voteapp" with the default driver

Pulling db (postgres:9.4)...

ucpdemo-0: Pulling postgres:9.4... : downloaded

ucpdemo-2: Pulling postgres:9.4... : downloaded

ucpdemo-1: Pulling postgres:9.4... : downloaded

Creating db

Pulling redis (redis:latest)...

ucpdemo-0: Pulling redis:latest... : downloaded

ucpdemo-2: Pulling redis:latest... : downloaded

ucpdemo-1: Pulling redis:latest... : downloaded

Creating redis

Pulling worker (docker/example-voting-app-worker:latest)...

Compose creates the `voteappbase_voteapp` network and deploys the application.

7. From UCP, go to the **Applications** page inside UCP.

Your new application should appear in the list.

8. Expand to the app to see which nodes the application containers are running in.


Now that the application is deployed and running, it's time to test it. To do

this, you configure a DNS mapping on the node where you are running

`votingapp_web-vote-app_1` container. browser. This maps the "votingapp.local"

DNS name to the public IP address of the `votingapp_web-vote-app_1` node.

1. Configure the DNS name resolution on your local machine for browsing.

- On Windows machines this is done by adding `votingapp.local <votingapp_web-vote-app_1-public-ip>` to the `C:\Windows\System32\Drivers\etc\hosts file`. Modifying this file requires administrator privileges. To open the file with administrator privileges, right-click `C:\Windows\System32\notepad.exe` and select `Run as administrator`. Once Notepad is open, click `file` > `open` and open the file and make the edit.

- On OSX machines this is done by adding `votingapp.local <votingapp_web-vote-app_1-public-ip>` to `/private/etc/hosts`.

- On most Linux machines this is done by adding `votingapp.local <votingapp_web-vote-app_1-public-ip>` to `/etc/hosts`.

Be sure to replace `<votingapp_web-vote-app_1-public-ip>` with the public IP address of

your `votingapp_web-vote-app_1` node. You can find the `votingapp_web-vote-app_1` node's Public IP by

selecting the node from within the UCP dashboard.

2. Verify the mapping worked with a `ping` command from your local machine.

ping votingapp.local

Pinging votingapp.local [54.183.164.230] with 32 bytes of data:

Reply from 54.183.164.230: bytes=32 time=164ms TTL=42

Reply from 54.183.164.230: bytes=32 time=163ms TTL=42

Reply from 54.183.164.230: bytes=32 time=169ms TTL=42

3. Point your web browser to `http://votingapp.local`.