Use HEALTHCHECK in Dockerfile to see if service is up & offering normal responses

The current Docker image is great. But I think it could be even better. How? Incorporating a simple HEALTHCHECK. Right now, a ‘docker ps’ will show that the process is running, but Docker has no notion of whether the process is healthy.

I’d propose with starting simple… a one-liner just to see if the service is listening on port 8123/tcp and offering a non-error http response. Over time this could be replaced with a shell script that performs a more comprehensive suite of tests.

The value? Running a ‘docker ps’ will report back not just that the container is running, but that it is still starting up, that it is healthy, or that it is unhealthy. This is really quite useful for more sophisticated orchestration around the container.

I’ve got the git repo forked now and I just took more time writing this than I’m likely to take implementing it. If accepted, this will be my first contribution to the project so please be compassionate with course corrections. :slight_smile:

@balloob your name is in the Dockerfile so pinging you for visibility/collab.

I have built a test image on my personal network with the health check baked in. Upon starting:

% docker ps ✹
efb0e616b5d8 731fe9aca770 “python -m homeassis…” 17 seconds ago Up 15 seconds (health: starting)>8123/tcp nervous_noyce

And after it’s up and serving pages:

% docker ps ✹
efb0e616b5d8 731fe9aca770 “python -m homeassis…” 38 seconds ago Up 37 seconds (healthy)>8123/tcp nervous_noyce

1 Like

Pull request:


What if the user enables ssl or if they change the port that Home Assistant uses?

What if the user enables ssl or if they change the port that Home Assistant uses?

All of that happens outside of the boundaries of the container. The healthcheck is run inside of the container. So it really doesn’t matter what port you export it to externally, or if you export it at all, or if you put a WAF or SSL gateway or reverse proxy in front of it. This runs entirely inside the home-assistant container and is blissfully unaware of what happens outside.

1 Like

Unfortunately, that is not true. Users can enable ssl and change ports in configuration.yaml, which will break the health check. Refer to for details on how that can be done.

That’s probably fine to do that if you’re running in bare metal. Doing something like that in a container is… weird.

Eh. It’s moot. My first and likely only attempt at contributing to this project was closed with a terse blow-off and no real conversation.

I’ll have to look into this myself even if I have to roll my own docker container builds. I’m already added a couple Python libraries to each update for some custom scripts, pushing in my pull request changes, and since 0.73 the restart function doesn’t work anymore so it would be cool to have something kick it back into service.

You where not blown off, there is a perfectly good explanation given of why it’s not being implemented, including some links to previous discussions.

Don’t give up, keep sharing idea’s!

I would also really appreciate this feature. I just mistakinly requested this feature on Github and it got closed. Then I found it already here. So, +1 for this. If the use cases for a stable HEALTHCHECK within a docker container vary too much, I suggest we find a more accurate way to do a HEALTHCHECK that fits all those cases.

My original request was here:


I just made a HEALTHCHECK script which read the configuration.yaml file.
It works on my docker configuration and isn’t heavily tested for now, but that’s my 2 cents! :wink:

Don’t hesitate to use the Issue tracker if you find some bugs…


This is not getting the attention it deserves. Adding the Healthcheck into the container would be a great feature for advanced users and it won’t require a huge change.


Agreed. I’d love to see this feature.


Would love to see this as well. Appears there is opposition from top level developers because not all users have a frontend (do not use HA via a web browser or app) and some users change the http port. I’d think this is a very small number of users that do either.

Even so, doing a couple things should mitigate these oppositions. First, the healthcheck shouldn’t be included in the Dockerfile. Meaning it shouldn’t be enabled by default. Second, it should only be a separate path with no authentication that returns 200 for healthy or 404 for unhealthy. An example path would be /health. It could even be a different port than the main HA instance, IE 8124.

Having the ability to do a healthcheck would be very beneficial to anyone running core.

Wish list:
It would be nice to have an interface to configure what makes the /health path return a 404. For instance, allow the selection of individual integrations that have failed or not loaded. IE automation, recorder. etc.

1 Like