README.md 4.73 KB
Newer Older
Mark Church's avatar
Mark Church committed
1
2
# Docker Pets

Mark Church's avatar
Mark Church committed
3
Docker Pets is a simple application that's useful for testing out features of Docker Enterprise Edition.
Mark Church's avatar
Mark Church committed
4
5
6
7
8
9

If you are interested in a guide on how to demo Docker Pets on the Universal Control Plane then check out [this tutorial](https://github.com/mark-church/docker-pets/blob/master/DEMO-DDC.md).


## Versioning

Mark Church's avatar
Mark Church committed
10
- `1.0` is the primary version that should be used for demos. `latest` is also tagged with `1.0`
Mark Church's avatar
Mark Church committed
11
12
13
14
15
16
17
18
19
20
21
22
23
24
- `2.0` is a version with minor visual changes. Use this to demonstrate rolling updates from `1.0` to `2.0`
- `broken` is a version that reports a failed healthcheck. Use this version to demonstrate an unsucessful rolling update.

## Application Architecture

`docker-pets` can be run as a stateless single-container application or as a multi-container stateful application. The following are the two images used to deploy `docker-pets`:

- `chrch/docker-pets` is a front-end Python Flask container that serves up random images of housepets, depending on the given configuration
- `consul` is a back-end KV store that stores the number of visits that the `web` services recieve. It's configured to bootstrap itself with 3 replicas so that we have fault tolerant persistence.

## Building Pets from Scratch
Pets is hosted on the Docker Hub at `chrch/docker-pets:latest` but you can also build it locally with the following steps

```
Mark Church's avatar
Mark Church committed
25
$ git clone https://github.com/dockersamples/docker-pets.git
Mark Church's avatar
Mark Church committed
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
$ cd docker-pets/web
$ docker build -t docker-pets .
```

## Running Pets as a Single Container, Stateless App
```
$ docker run -it -p 5000:5000 docker-pets
```


## Running Pets on Docker for Mac/Windows in Development
Docker Swarm can easily be set up to run applications on a single developer laptop. The full app can be brought up to run in the same way it would run in production. We use a compose v3 file to deploy a fully fault tolerant frontend and backend, along with the configurations, secrets, and networks required for the application to run.
pets
This is the full architecture that is deployed when using [pets-dev-compose.yml](https://github.com/mark-church/docker-pets/blob/master/pets-dev-compose.yml).

```
Mark Church's avatar
Mark Church committed
42
~$ git clone https://github.com/dockersamples/docker-pets.git
Mark Church's avatar
Mark Church committed
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

~/docker-pets$ docker -v
Docker version 1.13.1-rc1, build 2527cfc

~/docker-pets$ docker node ls
ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
fd3ovikiq7tzmdr70zukbsgbs *  moby      Ready   Active        Leader

~/docker-pets$ docker stack deploy -c pets-dev-compose.yml pets
```

![](docs/images/pets-dev-arch.png) 


## Pets configuration parameters
The `web` container has several configuration parameters as environment variables:


- **`DB`**: Tells `web` where to find `db`. Service name or `<ip>:<port>`.
- **`DEBUG`**: Puts `web` containers in to debug mode. When mounting a volume for code, they will restart automatically when they detect a change in the code. Defaults to off, set to `True` to turn on.
- **`ADMIN_PASSWORD_FILE`**: Turns secrets on. If set, will password protect the Admin Console of `web`. Set to the full location of the Swarm secret (`/run/secrets/< X >`)

## Exposed Services
- Client Web Access - (dev port `5000`, prod URL `pets.dckr.org`)
	- `/` shows the selected Pet
	- `/vote` displays the vote selection
	- `/health` displays the application health of the given container
	- `/kill` toggles the health off for one of the web servers
- Admin Console - (dev port `7000`, prod URL `admin.pets.dckr.org`)
	- `/` displays voting results, redirects to `/login` if secrets are configured
	- `/login` requests login password
- Consul Backend - (dev port `8500`, prod ephemeral port)
	- `/ui` displays Consul server UI

## Voting Option Configuration

- **`OPTION_A`**: Defaults to 'Cats'. Pictures located in `/docker-petspets/web/static/option_a`
- **`OPTION_B`**: Defaults to 'Dogs'. Pictures located in `/docker-pets/web/static/option_b`
- **`OPTION_C`**: Defaults to 'Whales'. Pictures located in `/docker-pets/web/static/option_c`





## Running Ppetsets on Docker UCP in Production
This [full length tutorial](https://github.com/mark-church/docker-pets/blob/master/DEMO-DDC.md) will show you how to deploy and demo DDC with the pets app.

Production apps have entirely different requirements when it comes to security, deployment, and also security. Fortunately, deployment on Swarm & UCP is very much the same from development to production. Some minor additions to our compose file add in capabilities for secrets and also for L7 load balancing.

This is the full architecture that is deployed when using [pets-prod-compose.yml](https://github.com/mark-church/docker-pets/blob/master/pets-prod-compose.yml).

```
$ echo "mysecret" | docker secret create admin_password_v1 -
$ docker stack deploy -c pets-prod-compose.yml pets
```

![](docs/images/pets-prod-arch.png)