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.
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:
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:
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
docker/.env. For example, to disable HTTP request logging, set:
To adjust the number of uWSGI processes (for example, to save memory), set:
Read more about configuring uWSGI in uWSGI documentation.
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
email@example.com email addresses.
The container is configured to start the SMTP listener conditionally, based
on the value of the
SMTPD_PORT environment value:
SMTPD_PORTenvironment variable is not set, the SMTP listener will not run.
SMTPD_PORTis set, the listener will run and listen on the specified port. You may also need to edit
docker-compose.ymlto expose the listening port (see the "ports" section under the "web" service in
The conditional logic lives in uWSGI configuration file, uwsgi.ini.
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-Protoheader sent by the end user.
X-Forwarded-Protoheader 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;
Pre-built Docker images, built from the Dockerfile in the
are available on Docker Hub.
The images are built automatically for every new release.
The Docker images:
smtpdin the background. You do not need to run them separately.
To use a pre-built image for Healthchecks version X.Y, in the
replace the "build" section with: