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 [email protected]
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. 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;
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