How to Debug a Docker Compose Build

How to Debug a Docker Compose Build

If you’re using docker-compose to build a Docker container setup and something’s not working, here’s a basic process you can follow to find out what happened, and get your containers up and running properly.

To put this into greater context, recently I was trying to create a Docker development environment for building a new Mezzio application. 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.

First up, review the Docker Compose configuration

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.

Then, check the state of each container

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.

Next, 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.

Cheeky book promotion. Skip over it and keep reading, if you're not interested.
Learn the Mezzio Framework's Fundamentals and Start Creating Great Apps - Today! Mezzio Essentials teaches you the fundamentals of PHP's Mezzio framework — the fundamentals that you need — to begin building get paid for applications with the Mezzio framework right away. It’s a practical, hands-on approach, which shows you just enough of about the underlying principles and concepts before stepping you through the process of creating an application. Learn More

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

Finally, 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 containers and, after a minute or so, had a working installation ready to use. Achievement unlocked!

        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, built with 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, follow these steps to debug a Docker Compose-based container configuration:

  • 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 with docker-compose up -d --build
  • Lather, rinse, repeat

If you need any further information, check out the official Docker Compose documentation, or post a question in a comment, and I’ll see if I can help out.


You might also be interested in...


Want more tutorials like this?

If so, enter your email address in the field below and click subscribe.

You can unsubscribe at any time by clicking the link in the footer of the emails you'll receive. Here's my privacy policy, if you'd like to know more. I use Mailchimp to send emails. You can learn more about their privacy practices here.


Join the discussion

comments powered by Disqus