Docker: Specify health check start period and interval

[scop]

To reach healthy state faster at startup.

https://docs.docker.com/reference/dockerfile/#healthcheck

[axllent]

Thanks. Unfortunately there are compatibility issues with --start-interval which is not supported on some Docker systems. Adding this as a default would therefore break on these systems.

From memory those timeout / delay options in Docker are quite a mess and very badly documented. I'm fairly sure that this is the main option you're after here (ie: the one that would actually make a real difference), so my question is, would an alternative (without --start-interval=1s) make much difference to what it is already?

[scop]

The default start interval, if unspecified, is 5s which is better than nothing. In order for it to kick in, start period needs to be set though, as start period does not have a good default. So start period let's say 5s or 10s without start interval would be ok and yield an improvement -- in practice decreasing reaching healthy state from the current 15s to 5s. So, that would be e.g.

HEALTHCHECK --interval=15s --start-period=10s CMD /mailpit readyz

5s is still a pretty bad developer experience, but an out of the box improvement anyway.

[scop]

Dropped --start-interval and force pushed, along with commit message elaborating the rationale some more as it might not be obvious.

Should that be a comment in the Dockerfile instead/in addition? For example

# --start-interval would be nice, but is reportedly not good compatibilitywise.
# --start-period makes the default start interval (typically 5s) kick in where available.

[axllent]

Thanks for the update. I gave this a test (locally), and it still took exactly 15 seconds before a healthy status, so it makes no difference at all between what you have added (edited) and what was there before. Adding back the --start-interval=1s however works as expected, a healthy status 1 second after startup (which is what you are after).

I then revisited the --start-interval issue I pointed to previously.... from what I read, this feature was added in Docker Engine 25.0 (released a year ago in January 2024), meaning when I last tested it (July 2024) it had obliviously not rolled out to all platforms yet, including my own (Ubuntu 22). I can't say whether I was using docker.io (Debian's version) or docker-ce (Docker's official version) at the time. Anyway, I've just tested on a few VMs including older Ubuntu versions (16 & 20) with the most updated (on those platforms) Docker versions and they all work fine with --start-interval=1s, so provided one is using a supported & updated OS, I think that option is now supported.

So the way I see it I have two choices:

1. Take a bit of a gamble and allow the original MR you provided, which will greatly improve the time-to-healthy (there's no question there)
2. Do nothing (as the modified MR doesn't actually improve the time-to-healthy). Custom healthcheck options can be set when starting any Docker container, so there are options for those who want a faster startup.

I think I'll go for option 1 (if you don't mind changing it back.... sorry to hassle you!) - with the condition that I may have to revert the change if I start getting bug reports. So if you don't mind reverting your change I will then merge that change. Thank you.

[scop]

I tested it yesterday too, and it (adding just the start period) made the described difference to me. I just retested, and it still does. Reproducer:

$ grep HEALTHCHECK Dockerfile
HEALTHCHECK --interval=15s --start-period=10s CMD /mailpit readyz
$ docker build -t meh .
[...]
$ docker run --rm --name mailpit-test -d meh; sleep 4; for i in {1..3}; do docker ps | grep mailpit-test; sleep 1; done
8f06168b525ab0ee2b30b5a9055a6177a1063a9db103a40790106a1f46277cd1
8f06168b525a   meh                                                                            "/mailpit"               4 seconds ago   Up 4 seconds (health: starting)   1025/tcp, 1110/tcp, 8025/tcp                  mailpit-test
8f06168b525a   meh                                                                            "/mailpit"               5 seconds ago   Up 5 seconds (health: starting)   1025/tcp, 1110/tcp, 8025/tcp                  mailpit-test
8f06168b525a   meh                                                                            "/mailpit"               6 seconds ago   Up 6 seconds (healthy)      1025/tcp, 1110/tcp, 8025/tcp                  mailpit-test

My docker is, on Ubuntu 24.10:

$ docker version
Client: Docker Engine - Community
 Version:           27.5.1
 API version:       1.47
 Go version:        go1.22.11
 Git commit:        9f9e405
 Built:             Wed Jan 22 13:41:13 2025
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          27.5.1
  API version:      1.47 (minimum version 1.24)
  Go version:       go1.22.11
  Git commit:       4c9b3b0
  Built:            Wed Jan 22 13:41:13 2025
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.7.25
  GitCommit:        bcc810d6b9066471b0b6fa75f557a15a1cbf31bb
 runc:
  Version:          1.2.4
  GitCommit:        v1.2.4-0-g6c52b3f
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

But I'm happy to pretend I didn't say any of the above and put --start-interval=1s back there :)

[scop]

But I'm happy to pretend I didn't say any of the above and put --start-interval=1s back there :)

Done in decd239

[axllent]

Thank you. It goes to show the differences between Docker versions... I'm using Ubuntu 24.10 too, but using the default docker.io which is currently version 26.1.3, and which doesn't reach a ready state any faster (without the --start-interval=1s) 🤷‍♂️

Anyway, this has been merged, and will be included in the next release (I try not release too often) ❤️