Healthchecks

Build Status Coverage Status

Screenshot of Welcome page

Screenshot of My Checks page

Screenshot of Period/Grace dialog

Screenshot of Cron dialog

Screenshot of Integrations page

healthchecks is a watchdog for your cron jobs. It's a web server that listens for pings from your cron jobs, plus a web interface.

It is live here: http://healthchecks.io/

The building blocks are:

Setting Up for Development

These are instructions for setting up healthchecks Django app in development environment.

The site should now be running at http://localhost:8000. To access Django administration site, log in as a super user, then visit http://localhost:8000/admin

Configuration

Site configuration is loaded from environment variables. This is done in hc/settings.py. Additional configuration is loaded from hc/local_settings.py file, if it exists. You can create this file (should be right next to settings.py in the filesystem) and override settings, or add extra settings as needed.

Configurations settings loaded from environment variables:

Environment variable Default value Notes
SECRET_KEY "---"
DEBUG True Set to False for production
ALLOWED_HOSTS * Separate multiple hosts with commas
DEFAULT_FROM_EMAIL "healthchecks@example.org"
USE_PAYMENTS False
REGISTRATION_OPEN True
DB "sqlite" Set to "postgres" or "mysql"
DB_HOST "" (empty string)
DB_PORT "" (empty string)
DB_NAME "hc" (PostgreSQL, MySQL) or "/path/to/project/hc.sqlite" (SQLite) For SQLite, specify the full path to the database file.
DB_USER "postgres" or "root"
DB_PASSWORD "" (empty string)
DB_CONN_MAX_AGE 0
DB_SSLMODE "prefer" PostgreSQL-specific, details
DB_TARGET_SESSION_ATTRS "read-write" PostgreSQL-specific, details
EMAIL_HOST "" (empty string)
EMAIL_PORT "587"
EMAIL_HOST_USER "" (empty string)
EMAIL_HOST_PASSWORD "" (empty string)
EMAIL_USE_TLS "True"
EMAIL_USE_VERIFICATION "True"
SITE_ROOT "http://localhost:8000"
SITE_NAME "Mychecks"
MASTER_BADGE_LABEL "Mychecks"
PING_ENDPOINT "http://localhost:8000/ping/"
PING_EMAIL_DOMAIN "localhost"
PING_BODY_LIMIT 10000 In bytes. Set to None to always log full request body
DISCORD_CLIENT_ID None
DISCORD_CLIENT_SECRET None
SLACK_CLIENT_ID None
SLACK_CLIENT_SECRET None
PUSHOVER_API_TOKEN None
PUSHOVER_SUBSCRIPTION_URL None
PUSHOVER_EMERGENCY_RETRY_DELAY 300
PUSHOVER_EMERGENCY_EXPIRATION 86400
PUSHBULLET_CLIENT_ID None
PUSHBULLET_CLIENT_SECRET None
TELEGRAM_BOT_NAME "ExampleBot"
TELEGRAM_TOKEN None
TWILIO_ACCOUNT None
TWILIO_AUTH None
TWILIO_FROM None
TWILIO_USE_WHATSAPP "False"
PD_VENDOR_KEY None
TRELLO_APP_KEY None
MATRIX_HOMESERVER None
MATRIX_USER_ID None
MATRIX_ACCESS_TOKEN None
APPRISE_ENABLED "False"
SHELL_ENABLED "False"

Some useful settings keys to override are:

SITE_ROOT is used to build fully qualified URLs for pings, and for use in emails and notifications. Example:

SITE_ROOT = "https://my-monitoring-project.com"

SITE_NAME has the default value of "Mychecks" and is used throughout the templates. Replace it with your own name to personalize your installation. Example:

SITE_NAME = "My Monitoring Project"

REGISTRATION_OPEN controls whether site visitors can create new accounts. Set it to False if you are setting up a private healthchecks instance, but it needs to be publicly accessible (so, for example, your cloud services can send pings).

If you close new user registration, you can still selectively invite users to your team account.

EMAIL_USE_VERIFICATION enables/disables the sending of a verification link when an email address is added to the list of notification methods. Set it to False if you are setting up a private healthchecks instance where you trust your users and want to avoid the extra verification step.

PING_BODY_LIMIT sets the size limit in bytes for logged ping request bodies. The default value is 10000 (10 kilobytes). You can remove the limit altogether by setting this value to None.

Database Configuration

Database configuration is loaded from environment variables. If you need to use a non-standard configuration, you can override the database configuration in hc/local_settings.py like so:

DATABASES = {
    'default': {
        'ENGINE':   'django.db.backends.postgresql',
        'NAME':     'your-database-name-here',
        'USER':     'your-database-user-here',
        'PASSWORD': 'your-database-password-here',
        'TEST': {'CHARSET': 'UTF8'},
        'OPTIONS': {
            ... your custom options here ...
        }
    }
}

Accessing Administration Panel

healthchecks comes with Django's administration panel where you can manually view and modify user accounts, projects, checks, integrations etc. To access it,

Sending Emails

healthchecks must be able to send email messages, so it can send out login links and alerts to users. Environment variables can be used to configure SMTP settings, or your may put your SMTP server configuration in hc/local_settings.py like so:

EMAIL_HOST = "your-smtp-server-here.com"
EMAIL_PORT = 587
EMAIL_HOST_USER = "username"
EMAIL_HOST_PASSWORD = "password"
EMAIL_USE_TLS = True

For more information, have a look at Django documentation, Sending Email section.

Receiving Emails

healthchecks comes with a smtpd management command, which starts up a SMTP listener service. With the command running, you can ping your checks by sending email messages to your-uuid-here@my-monitoring-project.com email addresses.

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 'foo@example.org' \
    --mail-rcpt '11111111-1111-1111-1111-111111111111@my-monitoring-project.com' \
    -F '='

Sending Status Notifications

healtchecks comes with a sendalerts management 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 sendalerts command like so:

$ ./manage.py sendalerts

In a production setup, you will want to run this command from a process manager like supervisor or systemd.

Database Cleanup

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:

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.

Integrations

Discord

To enable Discord integration, you will need to:

Pushover

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:

Telegram

For this to work, your SITE_ROOT needs to be correct and use "https://" scheme.

Apprise

To enable Apprise integration, you will need to:

Shell Commands

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_ENABLED environment variable to True.

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 sendalerts process, and will run with the same system permissions as the sendalerts process.

Running in Production

Here is a non-exhaustive list of pointers and things to check before launching a Healthchecks instance in production.