Bug Hunt

If Startup Goes Wrong

If you have taken all prescribed precautions and the container still crashes on startup, you have several ways to approach the problem. What most people don't know is that the Docker call at the command line, with which you start the container, also has an -e parameter, which you can use to overwrite the Dockerfile's ENTRYPOINT directly at the command line.

Additionally, you will also want to specify the -it parameters and make sure the -d parameter is missing in the container call. The Docker container then starts with the shell as its program; in the next step, you can then enter the command defined as the actual Dockerfile's ENTRYPOINT.

However, you should make sure the command doesn't try to disappear into the background as a daemon. Once these conditions are met, it quickly becomes clear what the problem is. A change to the Dockerfile is a remedy.

Incidentally, the value of CMD also can be overwritten at the command line. To do this, simply append the desired value to the Docker command. This method is practical because it is difficult to define parameters when defining the ENTRYPOINT; instead, you can pass them in using CMD.

Program Output

A key issue when debugging applications in Docker containers is their output to stdout and stderr. If the program in the ENTRYPOINT starts with the parameters from CMD, you won't notice a thing outside of the container. On normal systems, reading logs is not a big challenge: They run a syslog daemon, which collects output from the running programs and writes it to various logfiles. However, a Docker container does not have a separate syslog daemon.

In Docker, logging therefore works in a fundamentally different way than in normal systems. Because there is no systemd – or in fact any init system at all – in Docker containers, applications in Docker containers are usually designed for operation in the foreground. This setup works well as long as you adhere to the "one application per container" principle; then, the logs usually end up automatically in the stdout standard output channel.

The interesting thing here is that Docker has a logs operation that uses the host command line to display all of a container's output to its default output channel. If the application inside the container uses this channel diligently, the output becomes visible on the host. The command is very easy to use:

docker logs test

displays the output to stdout for the test Docker container. If you want to see the logfiles continuously, insert another -f between logs and test or your choice of container name. Basically docker logs works in a very similar way to tail -f.

As an alternative to docker logs -f, you also have the docker attach command. It simply replicates the input of the standard output channel in real time on the admin terminal and is therefore very similar to docker logs -f. In contrast to the contents of attach, the contents of docker logs can be displayed even if a container is not running – but the local image of the special container must not have been deleted with docker rm.

This property makes the command ideal for scenarios in which a container crashes immediately after docker run is called. The output of docker logs usually contains the reason; attach can only be used with a running container (Figure 2).

Figure 2: Docker's logs command outputs the contents of stdout, the default output channel of the container.

See What's Going On

The top tool is indispensable for many administrators: It displays the process table (i.e., a list of all processes currently running on the system, including their respective states). If you use Docker for containerization, you don't have to forgo such a process overview: docker top <Name> continuously displays the processes for the <Name> container at the command line.

If you follow the mantra of one process per container, the command's output will not be very extensive, but sometimes a container starts child processes or creates threads that can be observed with top. The docker ps command works in the same way, producing output similar to ps in the shell.