In the Healthchecks source code, /docker/ directory, you can find a sample configuration for running the project with Docker and Docker Compose.
Note: For the sake of simplicity, the sample configuration starts a single database node and a single web server node, both on the same host. It does not handle TLS termination.
Copy docker/.env.example
to docker/.env
and add your configuration in it.
As a minimum, set the following fields:
ALLOWED_HOSTS
– the domain name of your Healthchecks instance.
Example: ALLOWED_HOSTS=hc.example.org
.DEFAULT_FROM_EMAIL
– the "From:" address for outbound emails.EMAIL_HOST
– the SMTP server.EMAIL_HOST_PASSWORD
– the SMTP password.EMAIL_HOST_USER
– the SMTP username.SECRET_KEY
– secures HTTP sessions, set to a random value.SITE_ROOT
– The base public URL of your Healthchecks instance. Example:
SITE_ROOT=https://hc.example.org
.Create and start containers:
$ cd docker
$ docker-compose up
Create a superuser:
$ docker-compose run web /opt/healthchecks/manage.py createsuperuser
Open http://localhost:8000 in your browser and log in with the credentials from the previous step.
The reference Dockerfile uses uWSGI
as the WSGI server. You can configure uWSGI by setting UWSGI_...
environment
variables in docker/.env
. For example, to disable HTTP request logging, set:
UWSGI_DISABLE_LOGGING=1
To adjust the number of uWSGI processes (for example, to save memory), set:
UWSGI_PROCESSES=2
Read more about configuring uWSGI in uWSGI documentation.
SMTPD_PORT
Healthchecks comes with a smtpd
management command, which runs a SMTP listener
service. With the command running, you can ping your checks by sending email messages
to your-uuid-here@hc.example.org
email addresses.
The container is configured to start the SMTP listener conditionally, based
on the value of the SMTPD_PORT
environment value:
SMTPD_PORT
environment variable is not set, the SMTP listener will not run.SMTPD_PORT
is set, the listener will run and listen on the specified port.
You may also need to edit docker-compose.yml
to expose the listening port
(see the "ports" section under the "web" service in docker-compose.yml
).The conditional logic lives in uWSGI configuration file, uwsgi.ini.
See also: the PING_EMAIL_DOMAIN environment variable for customizing the domain part of the email addresses.
If you plan to expose your Healthchecks instance to the public internet, make sure you put a TLS-terminating reverse proxy or load balancer in front of it.
Important: This Dockerfile uses uWSGI, which relies on the X-Forwarded-Proto header to determine if a request is secure or not. Without this information you may run into HTTP 403 "CSRF verification failed." errors when using your Healthchecks instance. See this issue comment for more information.
Make sure your TLS-terminating reverse proxy:
X-Forwarded-Proto
header sent by the end user.X-Forwarded-Proto
header value to match the protocol of the original request
("http" or "https").For example, in NGINX you can use the $scheme
variable like so:
proxy_set_header X-Forwarded-Proto $scheme;
If you are using haproxy, you can do the same like so:
http-request set-header X-Forwarded-Proto https if { ssl_fc }
http-request set-header X-Forwarded-Proto http unless { ssl_fc }
When you upgrade the database version in docker-compose.yml
(for example,
from postgres:12
to postgres:16
), you will also need to upgrade your postgres
data directory. One way to do this is using the
pgautoupgrade container.
Steps:
db
and web
containers: docker compose stop
docker volume ls
pgautoupgrade
like so:docker run --rm --name pgauto -it \
--mount type=volume,source=<pg-volume-name-here>,target=/var/lib/postgresql/data \
-e POSTGRES_PASSWORD=password \
-e PGAUTO_ONESHOT=yes \
pgautoupgrade/pgautoupgrade:16-bookworm
docker-compose.yml
file to use the postgres:16
imagedocker compose up
Pre-built Docker images, built from the Dockerfile in the /docker/
directory,
are available on Docker Hub.
The images are built automatically for every new release.
The Docker images:
sendalerts
, sendreports
, and smtpd
in the background.
You do not need to run them separately.To use a pre-built image for Healthchecks version X.Y, in the docker-compose.yml
file
replace the "build" section with:
image: healthchecks/healthchecks:vX.Y