I built BeforeUp to catch Docker Compose problems before deployment

I've been working on a small open-source tool called BeforeUp, and I've just released its first stable version.

The idea came from a simple limitation of Docker Compose: a configuration can be perfectly valid while the Linux host isn't ready to run it.

For example, docker compose config can succeed even when a published port is already occupied or a required bind-mount directory doesn't exist.

Those are the kinds of problems BeforeUp is meant to catch.

A simple example

Consider this Compose configuration:

services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:18080:80"
    volumes:
      - type: bind
        source: ./public
        target: /usr/share/nginx/html
        bind:
          create_host_path: false

Imagine that port 18080 is already used by another process and the public directory hasn't been created.

Running:

docker compose config --quiet

can still return successfully. Compose has validated the configuration, but it hasn't checked whether all the required host-side conditions are satisfied.

BeforeUp adds that inspection:

beforeup check -f compose.yaml

In an isolated Linux test with those conditions, the tool reported:

PASS    COMPOSE
PASS    DAEMON
WARNING PORT_IN_USE
        Host tcp port 18080 already has a listener.

BLOCKER BIND_MISSING
        A bind source for this service does not exist.

1 blocker(s), 1 warning(s), 3 passed

The distinction between warnings and blockers is intentional. An occupied port isn't automatically proof that deployment will fail; the existing service might legitimately own it.

Checking changes to running projects

I also added a compare command:

beforeup compare -f compose.yaml

It inspects selected differences between a proposed Compose configuration and the containers already running for that project.

This includes changes to published ports, data mounts, declared environment settings and image references.

The comparison is read-only. BeforeUp doesn't recreate containers, pull images or modify the running stack. Environment values and sensitive bind-source paths are not printed in its reports.

What BeforeUp doesn't do

I wanted to keep the scope narrow.

BeforeUp doesn't predict whether an application will become healthy, whether an image can be downloaded or whether two services will communicate successfully.

It's not a replacement for Docker Compose, and a successful preflight isn't a deployment guarantee.

The current release targets Linux. Some environments, including rootless Docker and SELinux configurations, still need more independent testing.

Try it

BeforeUp v0.4.3 is available under the MIT license, with Linux AMD64/ARM64 binaries and Debian packages.

GitHub: https://github.com/BreezeDelegate/beforeup

Releases: https://github.com/BreezeDelegate/beforeup/releases/tag/v0.4.3

I'm especially interested in hearing from developers who deploy multiple Docker Compose projects on Linux hosts.

If you try BeforeUp and encounter a false positive, an unclear warning or a scenario it doesn't handle, I'd be interested in a reproducible example.

That's the feedback I'm looking for as the project develops.

Comments

[tamina]

The warning-versus-blocker distinction is the part I liked most — a port already in use is not always a reason to stop, but a missing bind-mount path is. The read-only compare command also looks useful for checking a proposed change against running containers without touching them. Do you have a sense yet of how it behaves under rootless Docker, since you flagged that as a caveat?

[Odinaka Robert Nnamani]

A valid config with an occupied port is the exact gap here. The read-only compare is what makes it usable.