This chapter covers

• Running interactive and daemon terminal programs in containers
• Basic Docker operations and commands
• Isolating programs from each other and injecting configuration
• Running multiple programs in a container
• Durable containers and the container life cycle
• Cleaning up

This example uses three containers. The first will run NGINX; the second will run a program called a mailer. Both of these will run as detached containers. Detached means that the container will run in the background, without being attached to any input or output stream. A third program named watcher will run as a monitoring agent in an interactive container. Both the mailer and watcher agent are small scripts created for this example. In this section, you’ll learn how to do the following:

• Create detached and interactive containers
• List containers on your system
• View container logs
• Stop and restart containers
• Reattach a terminal to a container
• Detach from an attached container

Without further delay, let’s get started filling your client’s order.

docker run -d \            1
    --name mailer \
    dockerinaction/ch2_mailer

• 1 Starts detached

This command uses the short form of the --detach flag to start a new container named mailer in the background. At this point, you’ve run two commands and delivered two-thirds of the system that your client wants. The last component, called the agent, is a good fit for an interactive container.

A terminal-based text editor is a great example of a program that requires an attached terminal. It takes input from the user via a keyboard (and maybe mouse) and displays output on the terminal. It is interactive over its input and output streams. Running interactive programs in Docker requires that you bind parts of your terminal to the input or output of a running container.

To get started working with interactive containers, run the following command:

docker run --interactive --tty \      1
    --link web:web \
    --name web_test \
    busybox:1.29 /bin/sh

• 1 Creates a virtual terminal and binds stdin

The command uses two flags on the run command: --interactive (or -i) and --tty (or -t). First, the --interactive option tells Docker to keep the standard input stream (stdin) open for the container even if no terminal is attached. Second, the --tty option tells Docker to allocate a virtual terminal for the container, which will allow you to pass signals to the container. This is usually what you want from an interactive command-line program. You’ll usually use both of these when you’re running an interactive program such as a shell in an interactive container.

Just as important as the interactive flags, when you started this container, you specified the program to run inside the container. In this case, you ran a shell program called sh. You can run any program that’s available inside the container.

The command in the interactive container example creates a container, starts a UNIX shell, and is linked to the container that’s running NGINX. From this shell, you can run a command to verify that your web server is running correctly:

wget -O - http://web:80/

It’s possible to create an interactive container, manually start a process inside that container, and then detach your terminal. You can do so by holding down the Ctrl (or Control) key and pressing P and then Q. This will work only when you’ve used the --tty option.

To finish the work for your client, you need to start an agent. This is a monitoring agent that will test the web server as you did in the preceding example and send a message with the mailer if the web server stops. This command will start the agent in an interactive container by using the short-form flags:

docker run -it \            1
    --name agent \
    --link web:insideweb \
    --link mailer:insidemailer \
    dockerinaction/ch2_agent

• 1 Creates a virtual terminal and binds stdin

When running, the container will test the web container every second and print a message like the following:

System up.

Now that you’ve seen what it does, detach your terminal from the container. Specifically, when you start the container and it begins writing System up, hold the Ctrl (or Control) key and then press P and then Q. After doing so, you’ll be returned to the shell for your host computer. Do not stop the program; otherwise, the monitor will stop checking the web server.

Although you’ll usually use detached or daemon containers for software that you deploy to servers on your network, interactive containers are useful for running software on your desktop or for manual work on a server. At this point, you’ve started all three applications in containers that your client needs. Before you can confidently claim completion, you should test the system.

The first thing you should do to test your current setup is check which containers are currently running by using the docker ps command:

docker ps

Running the command will display the following information about each running container:

At this point, you should have three running containers with names: web, mailer, and agent. If any is missing but you’ve followed the example thus far, it may have been mistakenly stopped. This isn’t a problem because Docker has a command to restart a container. The next three commands will restart each container by using the container name. Choose the appropriate ones to restart the containers that were missing from the list of running containers:

docker restart web
docker restart mailer
docker restart agent

Now that all three containers are running, you need to test that the system is operating correctly. The best way to do that is to examine the logs for each container. Start with the web container:

docker logs web

That should display a long log with several lines that contain this substring:

"GET / HTTP/1.0" 200

System up.

Tip

The docker logs command has a flag, --follow or -f, that will display the logs and then continue watching and updating the display with changes to the log as they occur. When you’ve finished, press Ctrl-C (or Command-C) to interrupt the logs command.

Now that you’ve validated that the containers are running and that the agent can reach the web server, you should test that the agent will notice when the web container stops. When that happens, the agent should trigger a call to the mailer, and the event should be recorded in the logs for both agent and mailer. The docker stop command tells the program with PID 1 in the container to halt. Use it in the following commands to test the system:

docker stop web       1
docker logs mailer    2

• 1 Stops the web server by stopping the container
• 2 Waits a couple of seconds and checks the mailer logs

Look for a line at the end of the mailer logs that reads like this:

Sending email: To: admin@work  Message: The service is down!

That line means the agent successfully detected that the NGINX server in the container named web had stopped. Congratulations! Your client will be happy, and you’ve built your first real system with containers and Docker.

Learning the basic Docker features is one thing, but understanding why they’re useful and how to use them to customize isolation is another task entirely.

Every running program—or process—on a Linux machine has a unique number called a process identifier (PID). A PID namespace is a set of unique numbers that identify processes. Linux provides tools to create multiple PID namespaces. Each namespace has a complete set of possible PIDs. This means that each PID namespace will contain its own PID 1, 2, 3, and so on.

Most programs will not need access to other running processes or be able to list the other running processes on the system. And so Docker creates a new PID namespace for each container by default. A container’s PID namespace isolates processes in that container from processes in other containers.

docker run -d --name namespaceA \
    busybox:1.29 /bin/sh -c "sleep 30000"
docker run -d --name namespaceB \
    busybox:1.29 /bin/sh -c "nc -l 0.0.0.0 -p 80"

docker exec namespaceA ps      1
docker exec namespaceB ps      2

Command 1 should generate a process list similar to the following:

PID   USER     TIME  COMMAND
  1   root     0:00  sleep 30000
  8   root     0:00  ps

Command 2 should generate a slightly different process list:

PID   USER     TIME  COMMAND
  1   root     0:00  nc -l 0.0.0.0 -p 80
  9   root     0:00  ps

In this example, you use the docker exec command to run additional processes in a running container. In this case, the command you use is called ps, which shows all the running processes and their PID. From the output, you can clearly see that each container has a process with PID 1.

Without a PID namespace, the processes running inside a container would share the same ID space as those in other containers or on the host. A process in a container would be able to determine what other processes were running on the host machine. Worse, processes in one container might be able to control processes in other containers. A process that cannot reference any processes outside its namespace is limited in its ability to perform targeted attacks.

Like most Docker isolation features, you can optionally create containers without their own PID namespace. This is critical if you are using a program to perform a system administration task that requires process enumeration from within a container. You can try this yourself by setting the --pid flag on docker create or docker run and setting the value to host. Try it yourself with a container running BusyBox Linux and the ps Linux command:

docker run --pid host busybox:1.29 ps     1

• 1 Should list all processes running on the computer

Because containers all have their own PID namespace, they both cannot gain meaningful insight from examining it, and can take more static dependencies on it. Suppose a container runs two processes: a server and a local process monitor. That monitor could take a hard dependency on the server’s expected PID and use that to monitor and control the server. This is an example of environment independence.

docker run -d --name webConflict nginx:latest
docker logs webConflict                            1
docker exec webConflict nginx -g 'daemon off;'     2

• 1 Output should be empty.
• 2 Starts a second NGINX process in the same container

The last command should display output like this:

2015/03/29 22:04:35 [emerg] 10#0: bind() to 0.0.0.0:80 failed (98:
Address already in use)
nginx: [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use)
...

The second process fails to start properly and reports that the address it needs is already in use. Called a port conflict, this is a common issue in real-world systems in which several processes are running on the same computer or multiple people contribute to the same environment. It’s a great example of a conflict problem that Docker simplifies and solves. Run each in a different container, like this:

docker run -d --name webA nginx:latest    1

docker logs webA                          2

docker run -d --name webB nginx:latest    3

docker logs webB                          4

• 1 Starts the first NGINX instance
• 2 Verifies that it is working; should be empty.
• 3 Starts the second instance
• 4 Verifies that it is working; should be empty

Environment independence provides the freedom to configure software taking dependencies on scarce system resources without regard for other co-located software with conflicting requirements. Here are some common conflict problems:

All these conflicts arise when one or more programs have a common dependency but can’t agree to share or have different needs. As in the earlier port conflict example, Docker solves software conflicts with such tools as Linux namespaces, resource limits, filesystem roots, and virtualized network components. All these tools are used to isolate software inside a Docker container.

In the preceding section, you saw how Docker helps you avoid software conflicts with process isolation. But if you’re not careful, you can end up building systems that create metaconflicts, or conflicts between containers in the Docker layer.

Your first instinct might be to simply start more web containers. But that’s not as simple as it looks. Identifying containers gets complicated as the number of containers increases.

docker run -d --name webid nginx      1

docker run -d --name webid nginx      2

• 1 Creates a container named "webid"
• 2 Creates another container named "webid"

The second command here will fail with a conflict error:

FATA[0000] Error response from daemon: Conflict. The name "webid" is
already in use by container 2b5958ba6a00. You have to delete (or rename)
that container to be able to reuse that name.

Using fixed container names such as web is useful for experimentation and documentation, but in a system with multiple containers, using fixed names like that can create conflicts. By default, Docker assigns a unique (human-friendly) name to each container it creates. The --name flag overrides that process with a known value. If a situation arises in which the name of a container needs to change, you can always rename the container with the docker rename command:

docker rename webid webid-old        1
docker run -d --name webid nginx     2

• 1 Renames the current web container to "webid-old"
• 2 Creates another container named "webid"

Renaming containers can help alleviate one-off naming conflicts but does little to help avoid the problem in the first place. In addition to the name, Docker assigns a unique identifier that was mentioned in the first example. These are hex-encoded 1024-bit numbers and look something like this:

7cb5d2b9a7eab87f07182b5bf58936c9947890995b1b94f412912fa822a9ecb5

When containers are started in detached mode, their identifier will be printed to the terminal. You can use these identifiers in place of the container name with any command that needs to identify a specific container. For example, you could use the previous ID with a stop or exec command:

docker exec \
    7cb5d2b9a7eab87f07182b5bf58936c9947890995b1b94f412912fa822a9ecb5 \
echo hello

docker stop \
    7cb5d2b9a7eab87f07182b5bf58936c9947890995b1b94f412912fa822a9ecb5

docker exec 7cb5d2b9a7ea ps
docker stop 7cb5d2b9a7ea

Neither of these IDs is particularly well suited for human use. But they work well with scripts and automation techniques. Docker has several means of acquiring the ID of a container to make automation possible. In these cases, the full or truncated numeric ID will be used.

The first way to get the numeric ID of a container is to simply start or create a new one and assign the result of the command to a shell variable. As you saw earlier, when a new container is started in detached mode, the container ID will be written to the terminal (stdout). You’d be unable to use this with interactive containers if this were the only way to get the container ID at creation time. Luckily, you can use another command to create a container without starting it. The docker create command is similar to docker run, the primary difference being that the container is created in a stopped state:

docker create nginx

The result should be a line like this:

b26a631e536d3caae348e9fd36e7661254a11511eb2274fb55f9f7c788721b0d

If you’re using a Linux command shell such as sh or bash, you can assign that result to a shell variable and use it again later:

CID=$(docker create nginx:latest)     1
echo $CID

• 1 This will work on POSIX-compliant shells.

Shell variables create a new opportunity for conflict, but the scope of that conflict is limited to the terminal session or current processing environment in which the script was launched. Those conflicts should be easily avoidable because one use or program is managing that environment. The problem with this approach is that it won’t help if multiple users or automated processes need to share that information. In those cases, you can use a container ID (CID) file.

Both the docker run and docker create commands provide another flag to write the ID of a new container to a known file:

docker create --cidfile /tmp/web.cid nginx     1

cat /tmp/web.cid                               2

Like the use of shell variables, this feature increases the opportunity for conflict. The name of the CID file (provided after --cidfile) must be known or have some known structure. Just like manual container naming, this approach uses known names in a global (Docker-wide) namespace. The good news is that Docker won’t create a new container by using the provided CID file if that file already exists. The command will fail just as it does when you create two containers with the same name.

Container identification can be tricky, but you can manage the issue by using the ID and name-generation features of Docker.

With this new knowledge, the new system might look something like this:

MAILER_CID=$(docker run -d dockerinaction/ch2_mailer)     1
WEB_CID=$(docker create nginx)

AGENT_CID=$(docker create --link $WEB_CID:insideweb \
    --link $MAILER_CID:insidemailer \
    dockerinaction/ch2_agent)

• 1 Make sure mailer from first example is running.

This snippet could be used to seed a new script that launches a new NGINX and agent instance for each of your client’s customers. You can use docker ps to see that they’ve been created:

docker ps

docker ps -a

Much of the work associated with installing software or maintaining a fleet of computers lies in dealing with specializations of the computing environment. These specializations come as global-scoped dependencies (for example, known host filesystem locations), hardcoded deployment architectures (environment checks in code or configuration), or data locality (data stored on a particular computer outside the deployment architecture). Knowing this, if your goal is to build low-maintenance systems, you should strive to minimize these things.

Docker has three specific features to help build environment-agnostic systems:

• Read-only filesystems
• Environment variable injection
• Volumes

Using read-only filesystems accomplishes two positive things. First, you can have confidence that the container won’t be specialized from changes to the files it contains. Second, you have increased confidence that an attacker can’t compromise files in the container.

To get started working on your client’s system, create and start a container from the WordPress image by using the --read-only flag:

docker run -d --name wp --read-only \
    wordpress:5.0.0-php7.2-apache

When this is finished, check that the container is running. You can do so using any of the methods introduced previously, or you can inspect the container metadata directly. The following command will print true if the container named wp is running, and false otherwise:

docker inspect --format "{{.State.Running}}" wp

The docker inspect command will display all the metadata (a JSON document) that Docker maintains for a container. The format option transforms that metadata, and in this case, it filters everything except for the field indicating the running state of the container. This command should simply output false.

docker logs wp

That command should output something like this:

WordPress not found in /var/www/html - copying now...
Complete! WordPress has been successfully copied to /var/www/html
... skip output ...
Wed Dec 12 15:17:36 2018 (1): Fatal Error Unable to create lock file: 
Bad file descriptor (9)

When running WordPress with a read-only filesystem, the Apache web server process reports that it is unable to create a lock file. Unfortunately, it does not report the location of the files it is trying to create. If we have the locations, we can create exceptions for them. Let’s run a WordPress container with a writable filesystem so that Apache is free to write where it wants:

docker run -d --name wp_writable wordpress:5.0.0-php7.2-apache

Now let’s check where Apache changed the container’s filesystem with the docker diff command:

docker container diff wp_writable
C /run
C /run/apache2
A /run/apache2/apache2.pid

docker logs wp2
WordPress not found in /var/www/html - copying now...
Complete! WordPress has been successfully copied to /var/www/html
... skip output ...
[Wed Dec 12 16:25:40.776359 2018] [mpm_prefork:notice] [pid 1] 
AH00163: Apache/2.4.25 (Debian) PHP/7.2.13 configured -- 
resuming normal operations
[Wed Dec 12 16:25:40.776517 2018] [core:notice] [pid 1] 
AH00094: Command line: 'apache2 -D FOREGROUND'

WordPress also has a dependency on a MySQL database. A database is a program that stores data in such a way that it’s retrievable and searchable later. The good news is that you can install MySQL by using Docker, just like WordPress:

docker run -d --name wpdb \
    -e MYSQL_ROOT_PASSWORD=ch2demo \
    mysql:5.7

Once that is started, create a different WordPress container that’s linked to this new database container:

docker run -d --name wp3 \         1
    --link wpdb:mysql \            2
    -p 8000:80 \                   3
    --read-only \
    -v /run/apache2/ \
    --tmpfs /tmp \
    wordpress:5.0.0-php7.2-apache

• 1 Uses a unique name
• 2 Creates a link to the database
• 3 Directs traffic from host port 8000 to container port 80

Check one more time that WordPress is running correctly:

docker inspect --format "{{.State.Running}}" wp3

The output should now be true. If you would like to use your new WordPress installation, you can point a web browser to http://127.0.0.1:8000.

An updated version of the script you’ve been working on should look like this:

#!/bin/sh

DB_CID=$(docker create -e MYSQL_ROOT_PASSWORD=ch2demo mysql:5.7)

docker start $DB_CID

MAILER_CID=$(docker create dockerinaction/ch2_mailer)
docker start $MAILER_CID

WP_CID=$(docker create --link $DB_CID:mysql -p 80 \
    --read-only -v /run/apache2/ --tmpfs /tmp \
    wordpress:5.0.0-php7.2-apache)

docker start $WP_CID

AGENT_CID=$(docker create --link $WP_CID:insideweb \
    --link $MAILER_CID:insidemailer \
    dockerinaction/ch2_agent)

docker start $AGENT_CID

But this design has two problems. First, the database is running in a container on the same computer as the WordPress container. Second, WordPress is using several default values for important settings such as database name, administrative user, administrative password, database salt, and so on.

To deal with this problem, you could create several versions of the WordPress software, each with a special configuration for the client. Doing so would turn your simple provisioning script into a monster that creates images and writes files. A better way to inject that configuration would be through the use of environment variables.

Environment variables are key/value pairs that are made available to programs through their execution context. They let you change a program’s configuration without modifying any files or changing the command used to start the program.

Docker uses environment variables to communicate information about dependent containers, the hostname of the container, and other convenient information for programs running in containers. Docker also provides a mechanism for a user to inject environment variables into a new container. Programs that know to expect important information through environment variables can be configured at container-creation time. Luckily for you and your client, WordPress is one such program.

Before diving into WordPress specifics, try injecting and viewing environment variables on your own. The UNIX command env displays all the environment variables in the current execution context (your terminal). To see environment variable injection in action, use the following command:

docker run --env MY_ENVIRONMENT_VAR="this is a test" \      1
    busybox:1.29 \
    env                                                     2

The --env flag, or -e for short, can be used to inject any environment variable. If the variable is already set by the image or Docker, the value will be overridden. This way, programs running inside containers can rely on the variables always being set. WordPress observes the following environment variables:

• WORDPRESS_DB_HOST
• WORDPRESS_DB_USER
• WORDPRESS_DB_PASSWORD
• WORDPRESS_DB_NAME
• WORDPRESS_AUTH_KEY
• WORDPRESS_SECURE_AUTH_KEY
• WORDPRESS_LOGGED_IN_KEY
• WORDPRESS_NONCE_KEY
• WORDPRESS_AUTH_SALT
• WORDPRESS_SECURE_AUTH_SALT
• WORDPRESS_LOGGED_IN_SALT
• WORDPRESS_NONCE_SALT

Tip

This example neglects the KEY and SALT variables, but any real production system should absolutely set these values.

To get started, you should address the problem that the database is running in a container on the same computer as the WordPress container. Rather than using linking to satisfy WordPress’s database dependency, inject a value for the WORDPRESS_DB_HOST variable:

docker create --env WORDPRESS_DB_HOST=<my database hostname> \
    wordpress: 5.0.0-php7.2-apache

This example would create (not start) a container for WordPress that will try to connect to a MySQL database at whatever you specify at <my database hostname>. Because the remote database isn’t likely using any default username or password, you’ll have to inject values for those settings as well. Suppose the database administrator is a cat lover and hates strong passwords:

docker create \
    --env WORDPRESS_DB_HOST=<my database hostname> \
    --env WORDPRESS_DB_USER=site_admin \
    --env WORDPRESS_DB_PASSWORD=MeowMix42 \
    wordpress:5.0.0-php7.2-apache

docker create --link wpdb:mysql \
    -e WORDPRESS_DB_NAME=client_a_wp \     1
    wordpress:5.0.0-php7.2-apache

docker create --link wpdb:mysql \
    -e WORDPRESS_DB_NAME=client_b_wp \     2
    wordpress:5.0.0-php7.2-apache

• 1 For client A
• 2 For client B

Now that you understand how to inject configuration into the WordPress application and connect it to collaborating processes, let’s adapt the provisioning script. First, let’s start database and mailer containers that will be shared by our clients and store the container IDs in environment variables:

export DB_CID=$(docker run -d -e MYSQL_ROOT_PASSWORD=ch2demo mysql:5.7)
export MAILER_CID=$(docker run -d dockerinaction/ch2_mailer)

Now update the client site provisioning script to read the database container ID, mailer container ID, and a new CLIENT_ID from environment variables:

#!/bin/sh

if [ ! -n "$CLIENT_ID" ]; then         1
    echo "Client ID not set"
    exit 1
fi

WP_CID=$(docker create \
    --link $DB_CID:mysql \             2
    --name wp_$CLIENT_ID \
    -p 80 \
    --read-only -v /run/apache2/ --tmpfs /tmp \
    -e WORDPRESS_DB_NAME=$CLIENT_ID \
    --read-only wordpress:5.0.0-php7.2-apache)

docker start $WP_CID

AGENT_CID=$(docker create \
        --name agent_$CLIENT_ID \
    --link $WP_CID:insideweb \
    --link $MAILER_CID:insidemailer \
    dockerinaction/ch2_agent)

docker start $AGENT_CID

If you save this script to a file named start-wp-for-client.sh, you can provision WordPress for the dockerinaction client by using a command like this:

CLIENT_ID=dockerinaction ./start-wp-multiple-clients.sh

The client should be pleased with what is being delivered. But one thing might be bothering you. In earlier testing, you found that the monitoring agent correctly notified the mailer when the site was unavailable, but restarting the site and agent required manual work. It would be better if the system tried to automatically recover when a failure was detected. Docker provides restart policies to help deal with that, but you might want something more robust.

Software may fail in rare conditions that are temporary in nature. Although it’s important to be made aware when these conditions arise, it’s usually at least as important to restore the service as quickly as possible. The monitoring system that you built in this chapter is a fine start for keeping system owners aware of problems with a system, but it does nothing to help restore service.

• Created
• Running
• Restarting
• Paused
• Removing
• Exited (also used if the container has never been started)

A basic strategy for recovering from temporary failures is automatically restarting a process when it exits or fails. Docker provides a few options for monitoring and restarting containers.

Docker provides this functionality with a restart policy. Using the --restart flag at container-creation time, you can tell Docker to do any of the following:

• Never restart (default)
• Attempt to restart when a failure is detected
• Attempt for some predetermined time to restart when a failure is detected
• Always restart the container regardless of the condition

Docker doesn’t always attempt to immediately restart a container. If it did, that would cause more problems than it solved. Imagine a container that does nothing but print the time and exit. If that container was configured to always restart, and Docker always immediately restarted it, the system would do nothing but restart that container. Instead, Docker uses an exponential backoff strategy for timing restart attempts.

A backoff strategy determines the amount of time that should pass between successive restart attempts. An exponential back-off strategy will do something like double the previous time spent waiting on each successive attempt. For example, if the first time the container needs to be restarted Docker waits 1 second, then on the second attempt it would wait 2 seconds, 4 seconds on the third attempt, 8 on the fourth, and so on. Exponential backoff strategies with low initial wait times are a common service-restoration technique. You can see Docker employ this strategy yourself by building a container that always restarts and simply prints the time:

docker run -d --name backoff-detector --restart always busybox:1.29 date

Then after a few seconds, use the trailing logs feature to watch it back off and restart:

docker logs -f backoff-detector

The only reason you might not want to adopt this directly is that during backoff periods, the container isn’t running. Containers waiting to be restarted are in the restarting state. To demonstrate, try to run another process in the backoff-detector container:

docker exec backoff-detector echo Just a Test

Running that command should result in an error message:

Container <ID> is restarting, wait until the container is running

That means you can’t do anything that requires the container to be in a running state, such as execute additional commands in the container. That could be a problem if you need to run diagnostic programs in a broken container. A more complete strategy is to use containers that start lightweight init systems.

An init system is a program that’s used to launch and maintain the state of other programs. Any process with PID 1 is treated like an init process by the Linux kernel (even if it is not technically an init system). In addition to other critical functions, an init system starts other processes, restarts them in the event that they fail, transforms and forwards signals sent by the operating system, and prevents resource leaks. It is common practice to use real init systems inside containers when that container will run multiple processes or if the program being run uses child processes.

docker exec lamp-test ps

The process list generated will list apache2 in the CMD column:

PID TTY          TIME CMD
  1 ?        00:00:00 supervisord
433 ?        00:00:00 mysqld_safe
835 ?        00:00:00 apache2
842 ?        00:00:00 ps

The values in the PID column will be different when you run the command. Find the PID on the row for apache2 and then insert that for <PID> in the following command:

docker exec lamp-test kill <PID>

Running this command will run the Linux kill program inside the lamp-test container and tell the apache2 process to shut down. When apache2 stops, the supervisord process will log the event and restart the process. The container logs will clearly show these events:

...
... exited: apache2 (exit status 0; expected)
... spawned: 'apache2' with pid 820
... success: apache2 entered RUNNING state, process has stayed up for >
      than 1 seconds (startsecs)

A common alternative to the use of init systems is using a startup script that at least checks the preconditions for successfully starting the contained software. These are sometimes used as the default command for the container. For example, the WordPress containers that you’ve created start by running a script to validate and set default environment variables before starting the WordPress process. You can view this script by overriding the default command with one to view the contents of the startup script:

docker run wordpress:5.0.0-php7.2-apache \
  cat /usr/local/bin/docker-entrypoint.sh

If you run through the displayed script, you’ll see how it validates the environment variables against the dependencies of the software and sets default values. Once the script has validated that WordPress can execute, it will start the requested or default command.

Startup scripts are an important part of building durable containers and can always be combined with Docker restart policies to take advantage of the strengths of each. Because both the MySQL and WordPress containers already use startup scripts, it’s appropriate to simply set the restart policy for each in an updated version of the example script.

Running startup scripts as PID 1 is problematic when the script fails to meet the expectations that Linux has for init systems. Depending on your use case, you might find that one approach or a hybrid works best.

With that final modification, you’ve built a complete WordPress site-provisioning system and learned the basics of container management with Docker. It has taken considerable experimentation. Your computer is likely littered with several containers that you no longer need. To reclaim the resources that those containers are using, you need to stop them and remove them from your system.

Ease of cleanup is one of the strongest reasons to use containers and Docker. The isolation that containers provide simplifies any steps that you’d have to take to stop processes and remove files. With Docker, the whole cleanup process is reduced to one of a few simple commands. In any cleanup task, you must first identify the container that you want to stop and/or remove. Remember, to list all the containers on your computer, use the docker ps command:

docker ps -a

Because the containers you created for the examples in this chapter won’t be used again, you should be able to safely stop and remove all the listed containers. Make sure you pay attention to the containers you’re cleaning up if there are any that you created for your own activities.

All containers use hard drive space to store logs, container metadata, and files that have been written to the container filesystem. All containers also consume resources in the global namespace such as container names and host port mappings. In most cases, containers that will no longer be used should be removed.

To remove a container from your computer, use the docker rm command. For example, to delete the stopped container named wp, you’d run this:

docker rm wp

You should go through all the containers in the list you generated by running docker ps -a and remove all containers that are in the exited state. If you try to remove a container that’s running, paused, or restarting, Docker will display a message like the following:

Error response from daemon: Conflict, You cannot remove a running
container. Stop the container before attempting removal or use -f
FATA[0000] Error: failed to remove one or more containers

The processes running in a container should be stopped before the files in the container are removed. You can do this with the docker stop command or by using the -f flag on docker rm. The key difference is that when you stop a process by using the -f flag, Docker sends a SIG_KILL signal, which immediately terminates the receiving process. In contrast, using docker stop will send a SIG_HUP signal. Recipients of SIG_HUP have time to perform finalization and cleanup tasks. The SIG_KILL signal makes for no such allowances and can result in file corruption or poor network experiences. You can issue a SIG_KILL directly to a container by using the docker kill command. But you should use docker kill or docker rm -f only if you must stop the container in less than the standard 30-second maximum stop time.

In the future, if you’re experimenting with short-lived containers, you can avoid the cleanup burden by specifying --rm on the command. Doing so will automatically remove the container as soon as it enters the exited state. For example, the following command will write a message to the screen in a new BusyBox container, and the container will be removed as soon as it exits:

docker run --rm --name auto-exit-test busybox:1.29 echo Hello World
docker ps -a

The primary focus of the Docker project is to enable users to run software in containers. This chapter shows how you can use Docker for that purpose. The ideas and features covered include the following:

• Containers can be run with virtual terminals attached to the user’s shell or in detached mode.
• By default, every Docker container has its own PID namespace, isolating process information for each container.
• Docker identifies every container by its generated container ID, abbreviated container ID, or its human-friendly name.
• All containers are in any one of six distinct states: created, running, restarting, paused, removing, or exited.
• The docker exec command can be used to run additional processes inside a running container.
• A user can pass input or provide additional configuration to a process in a container by specifying environment variables at container-creation time.
• Using the --read-only flag at container-creation time will mount the container filesystem as read-only and prevent specialization of the container.
• A container restart policy, set with the --restart flag at container-creation time, will help your systems automatically recover in the event of a failure.
• Docker makes cleaning up containers with the docker rm command as simple as creating them.