Updated on August 15th, 2023 in #docker

Optional depends_on with Docker Compose v2.20.2+

This was possible with some earlier versions of Docker Compose v2 but it was technically classified as a bug.

Quick Jump: How Did We Arrive Here? | How Does It Work? | Demo Video

Prefer video? Here’s a recorded version of this post on YouTube which demonstrates this feature.

I’ve written about Docker Compose profiles and optional dependent services in the past but a few minor things have changed since then when Docker Compose v2 accidentally created a backwards incompatible change in v2.19.

How Did We Arrive Here?

Here’s a brief timeline:

• April 2022: Docker Compose v2 is considered GA (General Availability)
  • Optional depends_on was supported implicitly by accident
• June 2023: Docker Compose v2.19 is released
  • A breaking change requires all depends_on services to be set and available
• July 2023: Docker Compose v2.20.2 is released
  • A new required property is added to depends_on to make it explicitly optional

Back in September 2022 I opened an issue to augment the Docker Compose specification because there was talk of this feature being “fixed” without an official workaround. That would have introduced a breaking change that folks have been using for a year.

This wasn’t supposed to be fixed until a solution was provided by Docker Compose but I think things got lost over time since that proposal was about a year old.

After bringing it up with the Docker Compose development team (one of the perks of being a Docker Captain btw!), they were understanding of the problem and quickly worked on a solution. Not even a few weeks later they shipped v2.20.2 with the new feature.

I wish they made required: false be the default value so it’s a true backwards compatible enhancement because you do need to adjust your Docker Compose file to set required: false if you want the old behavior.

However, that property only exists for v2.20.2+ which means users must change their YAML configuration and be using at least this version. If you try to use this new property with an older version of Docker Compose it will fail.

It’s not the end of the world, I’m happy we arrived at a solution. Especially since all of this will blow over and be the new norm within a few months.

Docker Desktop v4.22.0 supports this new version of Docker Compose v2 and it’s been available without DD for a while now too. If you’re reading this post and can upgrade versions you can start using this feature no matter how you’re running Docker!

How Does It Work?

Let’s say you only want to run postgres and redis in development because you use managed services in production or perhaps you have esbuild and tailwind watchers running in development but not in production.

That’s 2 common use cases of wanting optional depends_on, so now let’s say you have web and worker services defined with depends_on attached to them:

Before v2.19 (with the “bug”):

depends_on:
  - "postgres"
  - "redis"

If you set COMPOSE_PROFILES="web,worker", Docker Compose would silently allow your project to be upped without postgres and redis. This is essentially optional dependencies since it worked with or without them set to run.

After and including v2.19 (without the “bug”):

depends_on:
  - "postgres"
  - "redis"

If you set COMPOSE_PROFILES="web,worker", Docker Compose would fail to start and say you need to run postgres and redis. If you want them to always be required you can leave things how they are and you’re good to go.

After and including v2.20.2 (without the “bug”):

  depends_on:
    postgres:
      condition: "service_started"
      required: false
    redis:
      condition: "service_started"
      required: false

Now you can set required to be true or false based on your preference. You can still use the shorthand array syntax if you want them to be required by default.

Sure it’s a little more typing but I’m ok with that. I actually like seeing the condition explicitly set too because it’s clear on what criteria is used to determine the dependent service is up.

I’ve applied this patch to all of my Docker web app examples for Flask, Rails, Django and Node and rolled it into my Build a SAAS App with Flask course as a free update.

The demo video below shows Docker Compose being upped with this property set to different values.

Demo Video

Timestamps

• 0:35 – Taking a quick look at the new required property of depends_on
• 1:18 – Demonstrating using profiles and optional depends_on
• 2:17 – You will need Docker Compose v2.20.2+ to use this
• 3:10 – It’s available in Docker Desktop v4.22.0+
• 3:42 – This starting with opening a proposal on the Docker Compose spec

Are you going to use this feature? Let us know below!