They say the longest journey begins with a single step. In this case, an application begins with a single image. More often than not, existing images will not be perfect fits. This will certainly be the case if you are deploying your own services.

It all starts with a Dockerfile. This file provides detailed instructions to Docker for building an image. There are a lot of things that can be done in a Dockerfile. Specific operating system packages or language libraries can be installed; configuration files can be put into place; and a default command can be set. It is best to base a new image for an application off an official image, when possible. For example, an application written in Ruby should be based off of the official ruby image. A full reference of the Dockerfile directives can be found at https://docs.docker.com/engine/reference/builder/ .

Once your images are built, you need to tell Docker how to run them. Docker Engine is limited in allowing you to define how containers work together. The Docker project provides a solution called Docker Compose. Docker Compose is a great tool for testing out deployments, defining how containers will interact or what external storage they need, or even as a lightweight orchestration tool.

Installing Docker Compose is easy. For Windows and OS X users, docker-compose installs as part of the Docker Toolbox and Docker for Mac and Windows. For Linux users, docker-compose can be downloaded from the Docker repository on GitHub. The following command from the Docker Compose documentation shows you how:

# curl -L https://github.com/docker/compose/releases/download/1.8.0  /docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

A Docker Compose file defines everything about an application. The services, volumes, networks, and dependencies can all be defined in one place. The configuration can be used locally to stand up a development environment, plugged into an existing continuous integration or continuous deployment system, or even used on a server to start production services. Later chapters will show better ways to manage running services.

Docker Compose looks for a file named docker-compose.yml in the current directory. An alternate file can be specified with the -f option. The file is formatted in YAML so it can be edited in any text editor.

Let's start with a very simple compose file that starts a single nginx container that listens on port 80. This is an analogous container started with docker run -p 80:80 nginx. The value for image can be any image on your server or on the registry just like in the docker run command:

version: '2' 
services: 
  web: 
    image...

The example in the previous section was fun but did not really gain us anything over using the docker command. Most Internet applications have multiple pieces. The most common example is a web application that loads data from a database.

In ch02/web-db of the docker-orchestration-examples repository there is a very simple application that loads a list of authors and books from MySQL and displays them on a web page. Here is a docker-compose.yml that defines the application:

version: '2' 
 
services: 
  web: 
    image: web-db:0.1 
    build: . 
    ports: 
      - 80:5000 
    env_file: 
      - db.env 
    entrypoint: ./start.pl --init --command shotgun 
  db: 
    image: mysql:5.7 
    env_file: 
      - db.env 

The first thing that you should notice is that there are two services defined. The first, web, is the web application. The second, db, is a MySQL container. Let's look at them one...