Healthcheck start_period is not supported but documentation says it is

[jdel]

Documentation states that from 2.1, start_period is supported in healthchecks, but it is not.
Source: https://docs.docker.com/compose/compose-file/compose-file-v2/#healthcheck

This compose will fail with services.nginx.healthcheck value Additional properties are not allowed ('start_period' was unexpected):

version: '2.2'
services:
  nginx:
    image: nginx:stable
    healthcheck:
      test: ["CMD", "curl", "-f", "localhost"]
      interval: 30s
      timeout: 5s
      retries: 1
      start_period: 30s

Changing version to 2.1, 3, 3.1, 3.2, 3.3 yields the same error message.

For reference:

$ docker-compose version                                                                                                                                            
docker-compose version 1.14.0, build c7bdf9e
docker-py version: 2.3.0
CPython version: 2.7.12
OpenSSL version: OpenSSL 1.0.2j  26 Sep 2016

$ docker version                                                                                                                                                      
Client:
 Version:      17.06.2-ce
 API version:  1.30
 Go version:   go1.8.3
 Git commit:   cec0b72
 Built:        Tue Sep  5 20:12:06 2017
 OS/Arch:      darwin/amd64

Server:
 Version:      17.06.2-ce
 API version:  1.30 (minimum version 1.12)
 Go version:   go1.8.3
 Git commit:   cec0b72
 Built:        Tue Sep  5 19:59:19 2017
 OS/Arch:      linux/amd64
 Experimental: false

[sepich]

It is already supported in stack compose 3.4 since docker 17.09 - docker/cli#475
But we using same docker-compose.yml also for 'docker-compose build' and v3.4 still unsupported via docker-compose 1.16.1

ERROR: Version in "./docker-compose.yml" is unsupported. You might be seeing this error because you're using the wrong Compose file version. Either specify a supported version (e.g "2.2" or "3.3") and place your service definitions under the `services` key, or omit the `version` key and place your service definitions at the root of the file to use version 1.
For more on the Compose file format versions, see https://docs.docker.com/compose/compose-file/

[shin-]

From the docs:

Note: The start_period option is a more recent feature and is only available with the 2.3 file format.

[Clcanny]

You can use start_period option in 3.7 version.

Client:
 Version:           18.06.0-ce
 API version:       1.38
 Go version:        go1.10.3
 Git commit:        0ffa825
 Built:             Wed Jul 18 19:05:26 2018
 OS/Arch:           darwin/amd64
 Experimental:      false

Server:
 Engine:
  Version:          18.06.0-ce
  API version:      1.38 (minimum version 1.12)
  Go version:       go1.10.3
  Git commit:       0ffa825
  Built:            Wed Jul 18 19:13:46 2018
  OS/Arch:          linux/amd64
  Experimental:     true

You can look at this website:

Note: start_period is only supported for v3.4 and higher of the compose file format.

[mtazzari]

I can get start_period to work properly using Compose file v3.7 and docker 18.09, however I got really confused by the docs:

• start_period is a property in the Compose file, while
• start-period is a docker command line parameter, see the Engine docs here.

It took me a while to realise the hyphen/underscore difference.
I am writing this hoping to save some time to other people...

[samgarvis]

Add sudo to the front of the docker-compose call

[quarky42]

I can see in Docker Desktop 4.34.2 with a container that has a healthcheck, start_period, timeout, interval, and retries that all of those values except the healthcheck itself are being respected when the container is created and being completely ignored when the container is stopped and restarted. The same bug exists when using the "start" button instead of restart. The healthcheck is a simple curl based one.

The result of this is that when a container is stopped and restarted, the bootup of the container is halted shortly after it is started and treated as if it has failed. The inspect shows that the healthcheck has failed rapidly 4 times in a row less than 1 second apart. The actual healthcheck configured in the docker-compose.yml is 20s apart.

When there are no other services booting up, this service normally takes about 15 seconds to boot and is being interrupted after about 5 seconds. Restarting the container appears to be using some sort of default healthcheck configuration instead of respecting what was defined in the docker-compose.yml

It appears that 7 years later the implementation of start_period and healthchecks still leaves a lot to be desired.

I can see when I inspect the container that there are 5 healthcheck failures and the container is shutdown before it has a chance to finish booting up. This matches what I see in the log output as the container is booting and is just stopped on the way to booting up. If any of those configs were being respected for a restarted container, it would have had enough time to boot up. The timeout, the interval between healthchecks, and the number of retries... any of these would have taken longer to to actually fail and the container would have had enough time to boot up. Since Docker is rushing the healhtchecks on a restarted container, it is deciding that the container is failed way too early on.