A cron monitoring tool written in Python & Django
Healthchecks is a cron job monitoring service. It listens for HTTP requests and email messages ("pings") from your cron jobs and scheduled tasks ("checks"). When a ping does not arrive on time, Healthchecks sends out alerts.
Healthchecks comes with a web dashboard, API, 25+ integrations for delivering notifications, monthly email reports, WebAuthn 2FA support, team management features: projects, team members, read-only access.
The building blocks are:
Healthchecks is licensed under the BSD 3-clause license.
Healthchecks is available as a hosted service at https://healthchecks.io/.
To set up Healthchecks development environment:
Install dependencies (Debian/Ubuntu):
$ sudo apt-get update $ sudo apt-get install -y gcc python3-dev python3-venv libpq-dev
Prepare directory for project code and virtualenv. Feel free to use a different location:
$ mkdir -p ~/webapps $ cd ~/webapps
Prepare virtual environment (with virtualenv you get pip, we'll use it soon to install requirements):
$ python3 -m venv hc-venv $ source hc-venv/bin/activate $ pip3 install wheel # make sure wheel is installed in the venv
Check out project code:
$ git clone https://github.com/healthchecks/healthchecks.git
Install requirements (Django, ...) into virtualenv:
$ pip install -r healthchecks/requirements.txt
Create database tables and a superuser account:
$ cd ~/webapps/healthchecks $ ./manage.py migrate $ ./manage.py createsuperuser
With the default configuration, Healthchecks stores data in a SQLite file
hc.sqlitein the checkout directory (
To use PostgreSQL or MySQL, see the section Database Configuration section below.
$ ./manage.py test
Run development server:
$ ./manage.py runserver
The site should now be running at
http://localhost:8000. To access Django administration site, log in as a superuser, then visit
Healthchecks reads configuration from environment variables.
Healthchecks comes with Django's administration panel where you can manually view and modify user accounts, projects, checks, integrations etc. To access it,
Healthchecks must be able to send email messages, so it can send out login links and alerts to users. Specify your SMTP credentials using the following environment variables:
EMAIL_HOST = "your-smtp-server-here.com" EMAIL_PORT = 587 EMAIL_HOST_USER = "smtp-username" EMAIL_HOST_PASSWORD = "smtp-password" EMAIL_USE_TLS = True
For more information, have a look at Django documentation, Sending Email section.
Healthchecks comes with a
smtpdmanagement command, which starts up a SMTP listener service. With the command running, you can ping your checks by sending email messages to
Start the SMTP listener on port 2525:
$ ./manage.py smtpd --port 2525
Send a test email:
$ curl --url 'smtp://127.0.0.1:2525' \ --mail-from '[email protected]' \ --mail-rcpt '[email protected]' \ -F '='
healtchecks comes with a
sendalertsmanagement command, which continuously polls database for any checks changing state, and sends out notifications as needed. Within an activated virtualenv, you can manually run the
sendalertscommand like so:
$ ./manage.py sendalerts
In a production setup, you will want to run this command from a process manager like supervisor or systemd.
With time and use the Healthchecks database will grow in size. You may decide to prune old data: inactive user accounts, old checks not assigned to users, records of outgoing email messages and records of received pings. There are separate Django management commands for each task:
Remove old records from
api_pingtable. For each check, keep 100 most recent pings:
$ ./manage.py prunepings
Remove old records of sent notifications. For each check, remove notifications that are older than the oldest stored ping for same check.
$ ./manage.py prunenotifications
Remove user accounts that match either of these conditions:
$ ./manage.py pruneusers
Remove old records from the
api_tokenbuckettable. The TokenBucket model is used for rate-limiting login attempts and similar operations. Any records older than one day can be safely removed.
$ ./manage.py prunetokenbucket
Remove old records from the
api_fliptable. The Flip objects are used to track status changes of checks, and to calculate downtime statistics month by month. Flip objects from more than 3 months ago are not used and can be safely removed.
$ ./manage.py pruneflips
When you first try these commands on your data, it is a good idea to test them on a copy of your database, not on the live database right away. In a production setup, you should also have regular, automated database backups set up.
Healthchecks optionally supports two-factor authentication using the WebAuthn standard. To enable WebAuthn support, set the
RP_ID(relying party identifier ) setting to a non-null value. Set its value to your site's domain without scheme and without port. For example, if your site runs on
Note that WebAuthn requires HTTPS, even if running on localhost. To test WebAuthn locally with a self-signed certificate, you can use the
runsslservercommand from the
Healthchecks supports external authentication by means of HTTP headers set by reverse proxies or the WSGI server. This allows you to integrate it into your existing authentication system (e.g., LDAP or OAuth) via an authenticating proxy. When this option is enabled, healtchecks will trust the header's value implicitly, so it is very important to ensure that attackers cannot set the value themselves (and thus impersonate any user). How to do this varies by your chosen proxy, but generally involves configuring it to strip out headers that normalize to the same name as the chosen identity header.
To enable this feature, set the
REMOTE_USER_HEADERvalue to a header you wish to authenticate with. HTTP headers will be prefixed with
HTTP_and have any dashes converted to underscores. Headers without that prefix can be set by the WSGI server itself only, which is more secure.
REMOTE_USER_HEADERis set, Healthchecks will: - assume the header contains user's email address - look up and automatically log in the user with a matching email address - automatically create an user account if it does not exist - disable the default authentication methods (login link to email, password)
To enable the Slack "self-service" integration, you will need to create a "Slack App".
To do so: * Create a new Slack app on https://api.slack.com/apps/ * Add at least one scope in the permissions section to be able to deploy the app in your workspace (By example
Bot Token Scopeshttps://api.slack.com/apps/APPID/oauth?). * Add a _redirect url in the format
SITE_ROOT/integrations/add_slack_btn/. For example, if your SITEROOT is
https://my-hc.example.orgthen the redirect URL would be `https://my-hc.example.org/integrations/addslackbtn/`. * Look up your Slack app for the Client ID and Client Secret at https://api.slack.com/apps/APPID/general? . Put them in
To enable Discord integration, you will need to:
SITE_ROOT/integrations/add_discord/. For example, if you are running a development server on
localhost:8000then the redirect URI would be
Pushover integration works by creating an application on Pushover.net which is then subscribed to by Healthchecks users. The registration workflow is as follows:
To enable the Pushover integration, you will need to:
PUSHOVER_SUBSCRIPTION_URLenvironment variables. The Pushover subscription URL should look similar to
Healthchecks uses signal-cli to send Signal notifications. Healthcecks interacts with signal-cli over DBus.
To enable the Signal integration:
dbus-sendexample given in the signal-cli instructions.
SIGNAL_CLI_ENABLEDenvironment variable to
settelegramwebhookmanagement command. This command tells Telegram where to forward channel messages by invoking Telegram's setWebhook API call:
$ ./manage.py settelegramwebhook Done, Telegram's webhook set to: https://my-monitoring-project.com/integrations/telegram/bot/
For this to work, your
SITE_ROOTneeds to be correct and use "https://" scheme.
To enable Apprise integration, you will need to:
bash pip install apprise
The "Shell Commands" integration runs user-defined local shell commands when checks go up or down. This integration is disabled by default, and can be enabled by setting the
SHELL_ENABLEDenvironment variable to
Note: be careful when using "Shell Commands" integration, and only enable it when you fully trust the users of your Healthchecks instance. The commands will be executed by the
manage.py sendalertsprocess, and will run with the same system permissions as the
To enable the Matrix integration you will need to:
MATRIX_environment variables. Example:
MATRIX_HOMESERVER=https://matrix.org [email protected]:matrix.org MATRIX_ACCESS_TOKEN=[a long string of characters returned by the login call]
Here is a non-exhaustive list of pointers and things to check before launching a Healthchecks instance in production.
manage.py compresscommand whenever files in the
manage.py collectstaticcommand whenever files in the
/static/directory change. This command collects all the static files inside the
static-collecteddirectory. Configure your web server to serve files from this directory under the