Exercise 1: Running images


Learn how to run images, either one-off or as a running service


In docker-speak, an image is a file (or set of files) that contain the application you want to run. You can copy images around, upload them, download them etc.

A container is a process that is started from an image. You can use the same image to run multiple containers, in the same way that you can use the same executable with many different arguments.

So, an image corresponds to files, a container corresponds to processes.

Running a simple command in a container

Docker images have a name and a tag. The default for the tag is ‘latest’, and can be omitted. If you ask docker to run an image that is not present on your system, it will download it from hub.docker.com first, then run it.

Most Linux distributions have pre-built images available on dockerhub, so you can readily find something to get you started. Let’s start with the official Ubuntu linux image, and run a simple ‘hello world’. The docker run command takes options first, then the image name, then the command and arguments to run follow it on the command line:

> docker run ubuntu /bin/echo 'hello world'
Unable to find image 'ubuntu:latest' locally
latest: Pulling from library/ubuntu
af49a5ceb2a5: Pull complete 
8f9757b472e7: Pull complete 
e931b117db38: Pull complete 
47b5e16c0811: Pull complete 
9332eaf1a55b: Pull complete 
Digest: sha256:3b64c309deae7ab0f7dbdd42b6b326261ccd6261da5d88396439353162703fb5
Status: Downloaded newer image for ubuntu:latest
hello world

Note docker uses the ‘ubuntu:latest’ tag, since we didn’t specify what version we want.

If we run the same command again, docker will find the image cached on our local disk, so it will run much faster:

> docker run ubuntu /bin/echo 'hello world'
hello world

Running an interactive command in an image

To do something more exciting, you might want an interactive shell, so you can poke around and do stuff. That’s easy:

> docker run -t -i ubuntu /bin/bash
root@c69d6f8d89bd:/# id
uid=0(root) gid=0(root) groups=0(root)
root@c69d6f8d89bd:/# ls
bin   dev  home  lib64  mnt  proc  run   srv  tmp  var
boot  etc  lib   media  opt  root  sbin  sys  usr
> exit # or hit control-D

The -t -i options make sure we can attach a terminal to the container, and we tell it to run our favourite shell as the application.

As you can see, you have root access in your container, and you are in what looks like a normal linux system. Now you can do whatever you like, e.g. install software and develop applications, all within the container of your choice.

This is a useful way of practicing and debugging the build process for an application while building a Dockerfile. Start with the base image, enter it with a shell, and learn what commands you need to run to build your package. Then capture those commands in the Dockerfile.

When the container environment gets messy, perhaps because you’ve installed stuff you didn’t really want, you quit the container, build your image with what you’ve learned so far, and start again, from that image. This way, you progress step by step to a working image. Then, you optimise it!

Making changes to a container

In an interactive shell in a container, you can change the container contents. But the changes do not persist once you exit the container. If you re-run the image, you get a new container, not a re-run of the one you modified. Let’s create a file in /tmp, then exit and restart the image, and look for the file:

> docker run -t -i ubuntu /bin/bash
root@1688f55c3418:/# touch /tmp/a-file.txt
root@1688f55c3418:/# ls -l /tmp/a-file.txt 
-rw-r--r-- 1 root root 0 Nov 30 17:50 /tmp/a-file.txt
root@1688f55c3418:/# exit
> docker run -t -i ubuntu /bin/bash
root@97b1e86df1f1:/# ls -l /tmp
total 0
root@97b1e86df1f1:/# exit

There are, of course, ways to make persistent changes to a container. More on that later.

So, can you get back to a container you modified before? Yes, actually, you can! Once a container exits docker keeps it cached for a while, so you can recover it. The docker ps command will tell you which containers are running now, and if you give it the --all flag, it tells you about containers that have exited, but still exist in the cache:

> docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
> docker ps --all
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS                      PORTS               NAMES
97b1e86df1f1        ubuntu              "/bin/bash"              5 minutes ago       Exited (0) 5 minutes ago                        backstabbing_brown
1688f55c3418        ubuntu              "/bin/bash"              5 minutes ago       Exited (0) 5 minutes ago                        ecstatic_hugle
c69d6f8d89bd        ubuntu              "/bin/bash"              9 minutes ago       Exited (0) 9 minutes ago                        sad_keller
960588723c36        ubuntu              "/bin/echo 'hello wor"   13 minutes ago      Exited (0) 13 minutes ago                       suspicious_mestorf
ffbb0f60bda6        ubuntu              "/bin/echo 'hello wor"   19 minutes ago      Exited (0) 19 minutes ago                       mad_booth

N.B. the container names, such as sad_keller above, are made up by docker at random. Use --name xyz to set the name explicitly yourself.

N.B. Since you’re using the same virtual machine for the docker and kubernetes exercises, if someone has already started the kubernetes system there may be a lot of containers running. Filter them out with grep: docker ps --all | grep -v k8s

we know the container we modified was the one before last, with ID 1688f55c3418. We can start it again, then attach a terminal to it, and look for the file we created in /tmp:

> docker start 1688f55c3418
> docker attach 1688f55c3418
root@1688f55c3418:/# ls -l /tmp
total 0
-rw-r--r-- 1 root root 0 Nov 30 17:50 a-file.txt

In general, you don’t want to do this much, it’s messy if you run lots of containers. But it’s useful to know, just in case you need it.

If you know you don’t want to re-start a container afer you’ve run it, you can tell docker to clean it up automatically when it exits, with the --rm flag. E.g.:

> docker run --rm ubuntu echo 'hello world'

Starting a long-running service in a container

Containers are useful for running services, like web-servers etc. Many come packaged from the developers, so you can start one easily, but first you need to find the one you want to run. You can either search on hub.docker.com, or you can use the docker search command. Nginx is a popular web-server, let’s look for that:

> docker search nginx
NAME                      DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
nginx                     Official build of Nginx.                        4719      [OK]       
jwilder/nginx-proxy       Automated Nginx reverse proxy for docker c...   877                  [OK]
richarvey/nginx-php-fpm   Container running Nginx + PHP-FPM capable ...   311                  [OK]
million12/nginx-php       Nginx + PHP-FPM 5.5, 5.6, 7.0 (NG), CentOS...   76                   [OK]
webdevops/php-nginx       Nginx with PHP-FPM                              63                   [OK]
maxexcloo/nginx-php       Framework container with nginx and PHP-FPM...   58                   [OK]
bitnami/nginx             Bitnami nginx Docker Image                      20                   [OK]
gists/nginx               Nginx on Alpine                                 8                    [OK]
evild/alpine-nginx        Minimalistic Docker image with Nginx            8                    [OK]
million12/nginx           Nginx: extensible, nicely tuned for better...   8                    [OK]
maxexcloo/nginx           Framework container with nginx installed.       7                    [OK]
webdevops/nginx           Nginx container                                 7                    [OK]
1science/nginx            Nginx Docker images based on Alpine Linux       4                    [OK]
ixbox/nginx               Nginx on Alpine Linux.                          3                    [OK]
drupaldocker/nginx        NGINX for Drupal                                3                    [OK]
yfix/nginx                Yfix own build of the nginx-extras package      2                    [OK]
frekele/nginx             docker run --rm --name nginx -p 80:80 -p 4...   2                    [OK]
servivum/nginx            Nginx Docker Image with Useful Tools            2                    [OK]
dock0/nginx               Arch container running nginx                    2                    [OK]
blacklabelops/nginx       Dockerized Nginx Reverse Proxy Server.          2                    [OK]
xataz/nginx               Light nginx image                               2                    [OK]
radial/nginx              Spoke container for Nginx, a high performa...   1                    [OK]
tozd/nginx                Dockerized nginx.                               1                    [OK]
c4tech/nginx              Several nginx images for web applications.      0                    [OK]
unblibraries/nginx        Baseline non-PHP nginx container                0                    [OK]

The official build of Nginx seems to be very popular, let’s go with that:

> docker run -p 8080:80 nginx
Unable to find image 'nginx:latest' locally
latest: Pulling from library/nginx
386a066cd84a: Pull complete 
386dc9762af9: Pull complete 
d685e39ac8a4: Pull complete 
Digest: sha256:3861a20a81e4ba699859fe0724dc6afb2ce82d21cd1ddc27fff6ec76e4c2824e
Status: Downloaded newer image for nginx:latest

Note the -p 8080:80 option. That tells docker to map port 80 in the container to port 8080 on the host, so you can communicate with it.

Note also that we didn’t tell docker what program to run, that’s baked into the container in this case. More on that later.

The next step depends on if you’re running on your own laptop, or on a remote virtual machine.

  • If you’re running docker on your laptop, go to your browser and enter localhost:8080 in the address bar, you should see a page with a Welcome to nginx! message.
  • If you’re running docker on a remote virtual machine, create another terminal session and SSH into the machine again, and run curl -s http://localhost:8080 | grep Welcome. You’ll see the source-code, but also the Welcome to nginx! embedded in there

On your terminal where you ran the docker command, you’ll see some log information: - - [30/Nov/2016:18:07:59 +0000] "GET / HTTP/1.1" 200 612 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:49.0) Gecko/20100101 Firefox/49.0" "-"
2016/11/30 18:07:59 [error] 7#7: *1 open() "/usr/share/nginx/html/favicon.ico" failed (2: No such file or directory), client:, server: localhost, request: "GET /favicon.ico HTTP/1.1", host: "localhost:8080" - - [30/Nov/2016:18:07:59 +0000] "GET /favicon.ico HTTP/1.1" 404 169 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:49.0) Gecko/20100101 Firefox/49.0" "-" - - [30/Nov/2016:18:07:59 +0000] "GET /favicon.ico HTTP/1.1" 404 169 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:49.0) Gecko/20100101 Firefox/49.0" "-"
2016/11/30 18:07:59 [error] 7#7: *1 open() "/usr/share/nginx/html/favicon.ico" failed (2: No such file or directory), client:, server: localhost, request: "GET /favicon.ico HTTP/1.1", host: "localhost:8080"

That’s a good start, but you now have a terminal tied up with nginx, and if you hit CTRL-C in that terminal, your web-server dies. We can run it in the background instead:

> docker run --detach -p 8080:80 nginx

Go back to your browser or command line, reload localhost:8080, and you should get the page loaded again.

That nice long hexadecimal string is the container-ID, which we can use to get access to its logfiles with the docker logs command:

> docker logs --follow 48a2dca14407484ca4e7f564d6e8c226d8fdd8441e5196577b2942383b251106 - - [30/Nov/2016:18:18:40 +0000] "GET / HTTP/1.1" 304 0 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:49.0) Gecko/20100101 Firefox/49.0" "-"

If you hit CTRL-C now, your container is still running, in the background. You can see this with the docker ps command:

> docker ps
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                           NAMES
48a2dca14407        nginx               "nginx -g 'daemon off"   3 minutes ago       Up 3 minutes        443/tcp,>80/tcp   pensive_booth

You can open a shell into the running container, if you wish. This can be handy for debugging. Let’s take a look at the processes running in our nginx server. We have to install the procps package first, because the official nginx container is very lightweight, and doesn’t have that in it by default:

> docker exec -t -i pensive_booth /bin/bash
root@48a2dca14407:/# apt-get update -y && apt-get install -y procps
root@48a2dca14407:/# ps auxww | grep ngin                                                                                                                
root         1  0.0  0.0  31764  5164 ?        Ss   18:58   0:00 nginx: master process nginx -g daemon off;
nginx        7  0.0  0.0  32156  2900 ?        S    18:58   0:00 nginx: worker process
root        15  0.0  0.0  11128  1036 ?        S+   18:59   0:00 grep ngin

Note that although you’ve installed the procps package in the container while it was running, we haven’t installed it in the image, only into this running instance of the image. So if you kill this container and start it again, it won’t have the procps package installed.

So now you’ve started nginx, how do you stop it? Use the docker stop command! You can give it either the container-ID or the name. You’ll notice docker has made up a name for you, pensive_booth in this case. You may have to scroll the window below to the right so you can see it, depending on your browser.

> docker ps
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                           NAMES
48a2dca14407        nginx               "nginx -g 'daemon off"   3 minutes ago       Up 3 minutes        443/tcp,>80/tcp   pensive_booth

> docker stop pensive_booth

> docker ps # check that it's gone
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES


You now know how to find a container that you want to run. You can start it, re-start it, run it as a detached service, attach a terminal to it for debugging, view the logs externally and even map ports between it and your host machine.

Best practices

  • avoid making too many interactive changes to containers, see later exercises for how to modify and build your own containers
  • prefer official images over those built by third-parties. Docker runs with privileges, so you have to be a bit careful what you run.