Deployment hangs on docker compose build

Problem

You may encounter a situation where your deployment in DeployHQ appears to freeze or hang when the docker compose build command is executed. The log output in the DeployHQ interface stops updating, and eventually, the deployment fails, even though the command runs successfully when you execute it manually on the server.

This issue is often seen when a base image is updated, as Docker needs to download new layers, which can be a time-consuming process with little to no output for several minutes.

Cause

This happens because of how Docker handles its log output by default. The output is buffered in chunks, which means it isn't streamed to the console line by line. When a build is slow, there can be long pauses between log output, and DeployHQ may interpret this lack of activity as a stalled or frozen process and stop receiving the log stream.

This is not a timeout of your SSH connection, but rather an issue with how the output is being buffered and displayed. The command is still running on the server; the log simply isn't making it back to the DeployHQ interface in a timely manner.

Solution

To resolve this, you need to tell Docker to stream its output in real-time, without buffering. You can do this by adding the --progress=plain flag to your docker compose build command.

This flag forces Docker to output logs immediately as they're generated, which keeps the log stream active and ensures DeployHQ continues to receive updates throughout the build process.

How to implement the fix

  1. Navigate to your repository's settings in DeployHQ.

  2. Go to the Servers & Groups section and select the server you're deploying to.

  3. In the Deployment Commands section, find the command that executes your Docker build.

  4. Add the --progress=plain flag to the command.

Before:

docker compose build

After:

docker compose build --progress=plain

By making this small change, your deployment logs will update continuously, preventing the deployment from hanging and allowing the build to complete successfully.