Healthchecks is open-source, and is licensed under the BSD 3-clause license.
As an alternative to using the hosted service at https://healthchecks.io, you have the option to host a Healthchecks instance yourself.
The building blocks are:
You can set up a development environment in a Python virtual environment on your local system to develop a new feature, write a new integration or test a bugfix.
The following instructions assume you are using a Debian-based OS.
Install dependencies:
$ sudo apt-get update
$ sudo apt-get install -y gcc python3-dev python3-venv
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
Check out project code:
$ git clone https://github.com/healthchecks/healthchecks.git
Install requirements (Django, ...) into virtualenv:
$ pip install wheel
$ 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.sqlite
in the project directory (~/webapps/healthchecks/
).
Run tests:
$ ./manage.py test
Run development server:
$ ./manage.py runserver
From another shell, run the sendalerts
management command, responsible for
sending out notifications:
$ ./manage.py sendalerts
At this point, the site should now be running at http://localhost:8000
.
Healthchecks comes with Django's administration panel where you can manually view and modify user accounts, projects, checks, integrations etc. To access it, if you haven't already, create a superuser account:
$ ./manage.py createsuperuser
Then, log into the site using the superuser credentials. Once logged in, click on the "Account" dropdown in top navigation, and select "Site Administration".
Healthchecks needs SMTP credentials to be able to send emails: login links, monitoring notifications, monthly reports.
Specify SMTP credentials using the EMAIL_HOST
, EMAIL_PORT
, EMAIL_HOST_USER
,
EMAIL_HOST_PASSWORD
, EMAIL_USE_SSL
, and EMAIL_USE_TLS
environment variables.
Example:
EMAIL_HOST=my-smtp-server-here.com
EMAIL_PORT=465
EMAIL_HOST_USER=my-username
EMAIL_HOST_PASSWORD=mypassword
EMAIL_USE_SSL = True
EMAIL_USE_TLS = False
You can read more about handling outbound email in the Django documentation, Sending Email section.
Healthchecks comes with a smtpd
management command, which starts up an
SMTP listener service. With the command running, you can ping your
checks by sending email messages.
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 '='
The sendalerts
management command continuously polls the database for any checks
changing state, and sends out notifications as needed.
When sendalerts
is not running, the Healthchecks instance will not send out any
alerts.
Within an activated virtualenv, run the sendalerts
command like so:
$ ./manage.py sendalerts
In a production setup, make sure the sendalerts
command can survive
server restarts.
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, and old records of outgoing email messages. There are separate Django management commands for each task:
Remove old records of sent notifications. For each check, remove notifications that are older than the oldest stored ping for the corresponding check.
$ ./manage.py prunenotifications
Remove inactive user accounts:
$ ./manage.py pruneusers
Remove old records from the api_tokenbucket
table. 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_flip
table. 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, and not on the live system.
In a production setup, you will want to run these commands regularly, as well as have regular, automatic database backups set up.
Get the source code.
See Configuration for a list of configuration options.