How to Do Basic Debugging With Docker Compose

Ever been using docker-compose to build a container setup, but something's not worked and you're not sure why? Well, here's a basic process you can follow to debug the situation, find out what happened, and get your containers up and running.

Are One or More Containers Not Working?

To put this into greater context, recently I was trying to create a Docker setup to run ownCloud 10.0. I needed this to work, so that I could research and test some of the changes that I had to make to the documentation.

I'd created a basic container configuration, using the php:7-apache container and MariaDB and thought that everything should be working as expected. However, when I attempted to run the installer, the database hostname wasn't able to be resolved, so the installed failed.

This seemed rather strange, as I didn't see anything strange in the console output (or so I thought) after I started the containers.

The first thing I thought to do was to access bash on the webserver container to try and ping the database to see if it could be accessed. Sure enough, I wasn't able to.

I thought that I must have misconfigured something. But on reviewing the configuration with a known working setup, nothing seemed out of the ordinary. However, the database server clearly wasn't working, for some reason.

So I decided to have a quick look at its state, by running docker-compose ps. On doing so, I saw the following output; note Exit 1 as the state for the database container.

While not that clear, nor insightful, it means that the container wasn't able to start successfully. As the webserver’s State is Up, it is running properly.

        Name                      Command               State          Ports
-----------------------------------------------------------------------------------
core1000_database_1    docker-entrypoint.sh mysqld      Exit 1
core1000_webserver_1   docker-php-entrypoint apac ...   Up       0.0.0.0:80->80/tcp

Note: to get the status of a particular container, add its name to the end of the command. For example: docker-compose ps database.

What Do The Logs Say?

Given that the database container had exited prematurely, it was time to get more detailed information about the problem that caused this to happen. To do that, I needed to find out what the logs contained.

The reason why is that this is not so different from any other form of debugging. If you want to know what's going on, the best place to look is the logs. They contain information such as ports already being in use, server misconfiguration, and so on.

To have a look at the logs for the database container, I used the command: docker-compose logs —follow database. You don't have to include the --follow flag. But I decided to, as I wanted to reload the page a few times and see the output scroll by, instead of having to call the command repeatedly.

On doing so, here's what I saw:

database_1   | error: database is uninitialized and password option is not specified
database_1   |   You need to specify one of MYSQL_ROOT_PASSWORD, MYSQL_ALLOW_EMPTY_PASSWORD and MYSQL_RANDOM_ROOT_PASSWORD

Fix the Problem, Rebuild the Containers, and Check Again

Turns out, I'd almost configured the containers correctly, but had forgot to configure a mandatory setting for the MariaDb container. Given that, I added a value for MYSQL_ROOT_PASSWORD, saved the file and ran docker-compose up -d --build database to rebuild and restart the database container.

This time, I paid more careful attention to the console output and definitely saw nothing out of the obvious. However, just to be sure, I ran docker-compose ps again, to ensure that both containers were up and running.

On doing so, sure enough, everything was working as expected. Given that, I reloaded the ownCloud 10.0 setup and, after a minute or so, had a working installation ready to use.

        Name                      Command               State           Ports
--------------------------------------------------------------------------------------
core1000_database_1    docker-entrypoint.sh mysqld      Up      0.0.0.0:3306->3306/tcp
core1000_webserver_1   docker-php-entrypoint apac ...   Up      0.0.0.0:80->80/tcp

In Conclusion

While this hasn't been the most in-depth of guides on how to debug a Docker configuration, when using docker-compose, it's covered the essentials.

It's covered how to determine if a container isn't working and how to find out more detailed information so that you can correct problems.

To summarise:

• Use docker-compose ps to see the state of all the containers
• Use docker-compose logs --follow to inspect the logs to find out what errors are occurring
• Fix the problem
• Rebuild and restart the containers
• Lather, rinse, repeat

If you need any further information, check out the official Docker Compose documentation, or tweet me and I'll see if I can help out.