How to Debug a Docker Compose Build

How to Debug a Docker Compose Build

If you’re using Docker Compose to deploy an application (whether locally or remotely) and something’s not working, here’s a concise approach you can use to debug the deployment and get your containers up and running properly.

To put this into greater context, recently I was trying to create a new Docker Compose configuration for a new Mezzio application I was building. I’d created the basic configuration which contained just two services:

  • One for the web server and PHP runtime; and
  • One for the database

The services used the official Docker Hub PHP and MariaDB images respectively. I thought that everything was going to work straight away. However, after starting the deployment I saw a stack trace in Firefox showing that the database hostname wasn’t able to be resolved by PHP, so the deployment failed.

This seemed rather strange, as I didn’t see anything strange in the Docker log output – or so I thought – after I started the containers. I stepped through my standard process of debugging a container-based application deployment, and quickly resolved the issue.

Given that I’ve been using this small process successfully for some time, I thought it worth sharing.

Review the Docker Compose configuration

I initially thought that I must have configured something incorrectly. 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.

Check the state of each container

So I decided to have a quick look at the database container’s state, by running docker-compose ps. On doing so, I saw the following output.

        Name                      Command               State          Ports
core1000_database_1 mysqld      Exit 1
core1000_php_1         docker-php-entrypoint apac ...   Up>80/tcp

Note Exit 1 as the value of the State column for the database container. While not necessarily that clear nor insightful on its own, it means that the container wasn’t able to start successfully and has exited.

To get the status of a particular container, add its name to the end of the command, as in the command below.

docker-compose ps database

Check the logs

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.

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, often times, is the logs. For Docker-based deployments, 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 docker compose logs 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

Fix the problem, restart the containers, and check again

Turns out, I’d almost configured the database container correctly. Unfortunately, I’d forgotten to configure a mandatory setting for the MariaDb container: MYSQL_ROOT_PASSWORD. Given that, I added a value for MYSQL_ROOT_PASSWORD, saved the file, and restarted the database container with the following commands:

docker-compose down database
docker-compose up -d --build database

This time, I paid closer attention to the console output. I saw nothing to indicate that the error was still occurring, but 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, as you can see in the example output below.

        Name                      Command               State           Ports
core1000_database_1 mysqld      Up>3306/tcp
core1000_php_1         docker-php-entrypoint apac ...   Up>80/tcp

Given that, the application was ready to use.

That’s a short process for debugging a Docker Compose deployment

While this hasn’t been the most in-depth of guides on how to debug a Docker Compose-based deployment, it’s covered the essentials. 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 to inspect the logs to find out what errors are occurring
  • Fix the problem
  • Restart the containers
  • 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.

If you’re just getting started using containers grab a copy of Deploy With Docker Compose. It'll teach you the six essentials steps to deploying applications with Docker Compose.

Do you need to get your head around Docker Compose quickly?

What about needing to dockerize existing applications to make them easier to deploy, reducing the time required for develwpers to get started on projects, or learning how to debug an existing Docker Compose-based app? Then this free book is for you!

You might also be interested in these tutorials too...

Deploying With Docker - Take 1, Or "Houston, We Have a Problem"
Wed, May 3, 2017

Deploying With Docker - Take 1, Or "Houston, We Have a Problem"

A little while ago, I wrote two parts in a multi-part series about using Docker. As someone who’s reasonably new to Docker — and been bitten by the Docker bug — I wanted to share what I’d learned, in the hopes that others may benefit.

How to Deploy a PHP App to Production With Docker Compose
Sun, Nov 12, 2023

How to Deploy a PHP App to Production With Docker Compose

Want to know how to deploy a PHP app to production (or any other remote environment)? In this tutorial, I’ll show you all the steps involved, and provide background information along the way, so you can build on what you’ll learn.

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