diff --git a/templates/docs/self_hosted.html b/templates/docs/self_hosted.html index db7e5d18..f0110973 100644 --- a/templates/docs/self_hosted.html +++ b/templates/docs/self_hosted.html @@ -59,11 +59,9 @@ $ ./manage.py migrate $ ./manage.py createsuperuser - -

With the default configuration, Healthchecks stores data in a SQLite file - hc.sqlite in the checkout directory (~/webapps/healthchecks).

-

At this point, the site should now be running at http://localhost:8000.

-

To access Django administration site, log in as a superuser, then -visit http://localhost:8000/admin/.

-

FIXME note about no email configuration, no sendalerts, and the devserver

+

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, +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".

+

Sending Emails

+

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, and EMAIL_USE_TLS environment variables. Example:

+
EMAIL_HOST=my-smtp-server-here.com
+EMAIL_PORT=587
+EMAIL_HOST_USER=my-username
+EMAIL_HOST_PASSWORD=mypassword
+EMAIL_USE_TLS = True
+
+ +

You can read more about handling outbound email in the 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.

+

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-hc.example.org' \
+    -F '='
+
+ +

Sending Status Notifications

+

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.

+

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, old records of outgoing email messages and old records of received pings. +There are separate Django management commands for each task:

+

Remove old records from the api_ping table. 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 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.

Next Steps

Get the source code.

See Configuration for a list of configuration options.

\ No newline at end of file diff --git a/templates/docs/self_hosted.md b/templates/docs/self_hosted.md index 889520da..f462f665 100644 --- a/templates/docs/self_hosted.md +++ b/templates/docs/self_hosted.md @@ -55,8 +55,8 @@ The following instructions assume you are using a Debian-based OS. $ ./manage.py migrate $ ./manage.py createsuperuser - With the default configuration, Healthchecks stores data in a SQLite file - `hc.sqlite` in the checkout directory (`~/webapps/healthchecks`). + With the default configuration, Healthchecks stores data in a SQLite file + `hc.sqlite` in the checkout directory (`~/webapps/healthchecks`). * Run tests: @@ -66,12 +66,115 @@ The following instructions assume you are using a Debian-based OS. $ ./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`. -To access Django administration site, log in as a superuser, then -visit `http://localhost:8000/admin/`. +## 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, +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". + +## Sending Emails + +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`, and `EMAIL_USE_TLS` environment variables. Example: + +```ini +EMAIL_HOST=my-smtp-server-here.com +EMAIL_PORT=587 +EMAIL_HOST_USER=my-username +EMAIL_HOST_PASSWORD=mypassword +EMAIL_USE_TLS = True +``` + +You can read more about handling outbound email in the Django documentation, +[Sending Email](https://docs.djangoproject.com/en/3.1/topics/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. + +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-hc.example.org' \ + -F '=' + +## Sending Status Notifications + +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. + +## 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, old records of outgoing email messages and old records of received pings. +There are separate Django management commands for each task: + +Remove old records from the `api_ping` table. 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 the corresponding check. + + $ ./manage.py prunenotifications + +Remove inactive user accounts: + +```bash +$ ./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. -FIXME note about no email configuration, no sendalerts, and the devserver +In a production setup, you will want to run these commands regularly, as well as +have regular, automatic database backups set up. ## Next Steps diff --git a/templates/docs/self_hosted_configuration.html b/templates/docs/self_hosted_configuration.html index 513c92ef..14413c7b 100644 --- a/templates/docs/self_hosted_configuration.html +++ b/templates/docs/self_hosted_configuration.html @@ -22,6 +22,7 @@ integration.

DEBUG

Default: True

A boolean that turns on/off debug mode.

+

Never run a Healthchecks instance in production with the debug mode turned on!

This is a standard Django setting, read more in Django documentation.

DEFAULT_FROM_EMAIL

@@ -115,6 +116,7 @@ set EMAIL_USE_VERIFICATION to False.

Default: None

MASTER_BADGE_LABEL

Default: same as SITE_NAME

+

The label for the "Overall Status" status badge.

MATRIX_ACCESS_TOKEN

Default: None

The Matrix bot user's access token, required by the Matrix @@ -149,8 +151,20 @@ The default value is 10000 (10 kilobytes). You can adjust the limit or you can r the it altogether by setting this value to None.

PING_EMAIL_DOMAIN

Default: localhost

+

The domain to use for generating ping email addresses. Example:

+
PING_EMAIL_DOMAIN=ping.my-hc.example.org
+
+ +

In this example, Healthchecks would generate ping email addresses similar +to 3f1a7317-8e96-437c-a17d-b0d550b51e86@ping.my-hc.example.org.

PING_ENDPOINT

-

Default: http://localhost:8000/ping/

+

Default: {SITE_ROOT}/ping/

+

The base URL to use for generating ping URLs. Example:

+
PING_ENDPOINT=https://ping.my-hc.example.org
+
+ +

In this example, Healthchecks would generate ping URLs similar +to https://ping.my-hc.example.org/3f1a7317-8e96-437c-a17d-b0d550b51e86.

PUSHBULLET_CLIENT_ID

Default: None

PUSHBULLET_CLIENT_SECRET

@@ -244,8 +258,12 @@ notifications. Healthcecks interacts with signal-cli over DBus.

SITE_ROOT

Default: http://localhost:8000

+

The base URL of this Healthchecks instance. Healthchecks uses SITE_ROOT whenever +it needs to construct absolute URLs.

SITE_NAME

Default: Mychecks

+

The display name of this Healthchecks instance. Healthchecks uses it throughout +web UI and documentation.

SLACK_CLIENT_ID

Default: None

The Slack Client ID, required by the Slack integration.

@@ -288,6 +306,10 @@ scheme.

The Telegram bot user's authentication token, required by the Telegram integration.

TRELLO_APP_KEY

Default: None

+

The Trello app key, required by the Trello integration.

+

To set up the Trello integration, get a developer API key from +https://trello.com/app-key and put it in the +TRELLO_APP_KEY environment variable.

TWILIO_ACCOUNT

Default: None

TWILIO_AUTH

diff --git a/templates/docs/self_hosted_configuration.md b/templates/docs/self_hosted_configuration.md index 73282a6f..aefc7f97 100644 --- a/templates/docs/self_hosted_configuration.md +++ b/templates/docs/self_hosted_configuration.md @@ -37,6 +37,8 @@ Default: `True` A boolean that turns on/off debug mode. +_Never run a Healthchecks instance in production with the debug mode turned on!_ + This is a standard Django setting, read more in [Django documentation](https://docs.djangoproject.com/en/3.1/ref/settings/#debug). @@ -193,6 +195,8 @@ Default: `None` Default: same as `SITE_NAME` +The label for the "Overall Status" status badge. + ## `MATRIX_ACCESS_TOKEN` Default: `None` @@ -245,9 +249,27 @@ the it altogether by setting this value to `None`. Default: `localhost` +The domain to use for generating ping email addresses. Example: + +```ini +PING_EMAIL_DOMAIN=ping.my-hc.example.org +``` + +In this example, Healthchecks would generate ping email addresses similar +to `3f1a7317-8e96-437c-a17d-b0d550b51e86@ping.my-hc.example.org`. + ## `PING_ENDPOINT` -Default: `http://localhost:8000/ping/` +Default: `{SITE_ROOT}/ping/` + +The base URL to use for generating ping URLs. Example: + +```ini +PING_ENDPOINT=https://ping.my-hc.example.org +``` + +In this example, Healthchecks would generate ping URLs similar +to `https://ping.my-hc.example.org/3f1a7317-8e96-437c-a17d-b0d550b51e86`. ## `PUSHBULLET_CLIENT_ID` @@ -390,10 +412,16 @@ To enable the Signal integration: Default: `http://localhost:8000` +The base URL of this Healthchecks instance. Healthchecks uses `SITE_ROOT` whenever +it needs to construct absolute URLs. + ## `SITE_NAME` Default: `Mychecks` +The display name of this Healthchecks instance. Healthchecks uses it throughout +web UI and documentation. + ## `SLACK_CLIENT_ID` Default: `None` @@ -453,6 +481,12 @@ The Telegram bot user's authentication token, required by the Telegram integrati Default: `None` +The [Trello](https://trello.com/) app key, required by the Trello integration. + +To set up the Trello integration, get a developer API key from +[https://trello.com/app-key](https://trello.com/app-key) and put it in the +`TRELLO_APP_KEY` environment variable. + ## `TWILIO_ACCOUNT` Default: `None`