introduce up --wait condition

[ndeloof]

What I did
introduced compose up --wait to run detached BUT wait for services to reach state running or healthy (for those with a Healthcheck defined).

Typical usage is to have some backend services (let's say postgres database) ran by compose, and user need to wait for service to be actually up so he can apply database migrations and start an happy coding day.

services:
  db:
    image: postgres:alpine
    ports: ...
    healthcheck:
      test: ['CMD', 'pg_isready']  

$ docker compose up -d --wait
(...)
$ rake db:migrate

Related issue
#8351

(not mandatory) A picture of a cute animal, if possible in relation with what you did

[thaJeztah]

Wondering why this should not be the default for -d / --detach; -d would mean that you want the stack/project to be running in the background, which shouldn't be mutually exclusive with "keep the cli running until it reaches that state", similar to how docker service create waits for the service to reconcile its desired state. One thing that may changing in that case is a way to detach from the client (so that deploying the stack can continue).

[ndeloof]

Wondering why this should not be the default for -d

we hardly can change the existing behavior

[thaJeztah]

So, it currently already waits for things to be created, and started. Are there any cases where the up action to be considered "complete" until services have become healthy? (curious)

Looking at available options; what does ServiceConditionStarted do? (isn't that the same as the default?)

[ndeloof]

"service_started" indeed is the default condition.

Are there any cases where the up action to be considered "complete" until services have become healthy? (curious)

First, service might not define a healthcheck. Other than that, this is just how things used to be, aka "Legacy"

[mik-laj]

Do we need any unit tests, integration tests, E2E tests?

[thaJeztah]

service might not define a healthcheck

For that case, we should consider "running" to be the equivalent of "healthcheck==ok". Healthcheck during startup is just a more customized "readiness" check. If there's no customized one, then "container running" means it's ready.

Curious; what's the current behavior in this PR if I would pass a --wait on a service that doesn't have a healthcheck?

[ndeloof]

I don't think we should assume healthy == running, better detect container has no healthcheck configuration (by ContainerInspect.Config.Healthcheck) and report an error

[ndeloof]

we actually already return error when service/docker image doesn't define a healthcheck

[ndeloof]

@ulyssessouza any thoughts?

[thaJeztah]

I don't think we should assume healthy == running

The point is that the general design for healthchecks was to (during startup) be a readiness check; in that design "no healthcheck" implicitly means "no readiness checck, so running == "healthy"

better detect container has no healthcheck configuration (by ContainerInspect.Config.Healthcheck) and report an error

So, what are the other options?

• started is the default
• healthy will error if the service doesn't have a healthcheck
• completed_successfully ??? not sure what this does; wait for the container to exit?

I'm personally still in favor of making this part of the standard behavior; we'e already printing the steps taken to bring up the stack, so it would be one more output to that list

• creating network
• creating volumes
• start services
• wait for services to be running
• (*) waiting for services to be healthy

The UX would be more logical for docker compose up to stay attached until the project is deployed (similar to docker service create). After all; the project won't be functional until it's healthy?

[ndeloof]

The point is that the general design for healthchecks was to (during startup) be a readiness check; in that design "no healthcheck" implicitly means "no readiness checck, so running == "healthy"

There's indeed no distinction in docker between "ready" and "healthy", but I think we can assume actual usages based on this. Better reject a --wait when no healthcheck is set than pretending to be clever.

So, what are the other options?
started is the default

Then this flag is not needed. compose up -d already exit after all containers have been started

healthy will error if the service doesn't have a healthcheck

this is what's implemented here

completed_successfully ??? not sure what this does; wait for the container to exit?

yep. Basically, init container.

I'm personally still in favor of making this part of the standard behavio

This is all about backward compatibilty, can't just change the behavior for a command used by thousands (millions?) because is looks niceer

[thaJeztah]

we can assume actual usages based on this.

I'm not sure what you mean with this "assume actual usages"

than pretending to be clever.
..
yep. Basically, init container.

For both cases, the --wait would be for the service to reach/reconcile with it's expected state, which could be "running" (no healthcheck), "healthy" (with healthcheck), or "exited succesfully" (init containers)

This is all about backward compatibilty, can't just change the behavior for a command used by thousands (millions?) because is looks niceer

I think we're waaaay past "backward compatiblity" when we did #8655. We could still use the --compatibility flag for that if it's a real concern.

because is looks niceer

It's not "looking nicer"; I think the current behavior could be considered a bug; the expectation of a compose up would be to deploy the project (as described in the compose file), and detach once it succesfully did so. not waiting for that, means the project deployment didn't finish.

[ndeloof]

#8655 changes container names, but doesn't prevent most users to compose up and keep running the same commands they're used to
changing the behavior for up to wait for healthcheck status would make many user suddenly get up to get stuck for minutes without any extra logs. I can't imagine the number of issues we would receive about this.

[ndeloof]

seems we hardly can find a consensus here.

Here is my last proposal, reducing the scope:
Introduce --wait flag to wait for all services to reach either the running state or healthy for those who define a healthcheck test (either by compose file or image)

[ndeloof]

implemented the proposed "simpler" --wait boolean flag. Please reconsider

[noorul]

How long does this wait?

[ndeloof]

@noorul wait until dependent service reports a healthy state, as configured by HEALTHCHECK

[noorul]

@ndeloof I think a timeout option will add value here instead of waiting forever.

[nawa]

@ndeloof Thanks for the useful feature

Do you have a proposal how to avoid the issue with init containers that exit with 0 status as a result and it is totally ok. But --wait expects that all containers described in config are in running status

services:
    db:
        image: mysql:8.0
    
    init-db:
        image: mysql:8.0
        command: ./init-db.sh
        environment:
            <<: *cenv
        volumes:
            - ./init-db.sh:./init-db.sh
        depends_on:
            db:
                condition: service_started

docker compose up -d --wait

[AndreasXsenda]

@nawa Had the same issue and took me a while to find a work around. I use the command in a github action, which fails when the init container exits.

In case anyone else stumbles upon this, I separated it into two commands:

docker compose up db -d --wait
docker compose up init-db

Does anyone have a more elegant solution?