healthchecks_healthchecks/docker
Pēteris Caune db31cacc86
Fix syntax
2024-02-16 12:37:59 +02:00
..
.env.example Fix syntax 2024-02-16 12:37:59 +02:00
Dockerfile Update Dockerfile to use Python 3.12 2023-12-15 11:15:42 +02:00
README.md Fix MariaDB version check 2024-02-09 14:01:48 +02:00
docker-compose.yml Update uwsgi.ini to allow UWSGI_PROCESSES env var to override it 2023-10-17 10:24:20 +03:00
uwsgi.ini Increase uWSGI buffer size to allow requests with large cookies 2023-12-15 13:43:27 +02:00

README.md

Running with Docker

This is a sample configuration for running Healthchecks 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.

Getting Started

  • 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:

    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.

uWSGI Configuration

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.

SMTP Listener Configuration via 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@your-hc-domain.com email addresses.

The container is configured to start the SMTP listener conditionally, based on the value of the SMTPD_PORT environment value:

  • If SMTPD_PORT environment variable is not set, the SMTP listener will not run.
  • If 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.

TLS Termination

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:

  • Discards the X-Forwarded-Proto header sent by the end user.
  • Sets the 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;

Pre-built Images

Pre-built Docker images, built from the Dockerfile in this directory, are available on Docker Hub. The images are built automatically for every new release.

The Docker images:

  • Support amd64, arm/v7 and arm64 architectures.
  • Use uWSGI as the web server. uWSGI is configured to perform database migrations on startup, and to run sendalerts, sendreports, and smtpd in the background. You do not need to run them separately.
  • Ship with both PostgreSQL and MySQL database drivers.
  • Serve static files using the whitenoise library.
  • Have the apprise library preinstalled.
  • Do not handle TLS termination. In a production setup, you will want to put the Healthchecks container behind a reverse proxy or load balancer that handles TLS termination.

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