harmacist/healthchecks
1
0
Fork 0
forked from GithubBackups/healthchecks
Code Issues Pull Requests Projects Releases Wiki Activity

Add more content from README

Browse Source
This commit is contained in:
Pēteris Caune 2021-01-21 13:57:55 +02:00
parent 7e6afba8bd
commit 376d80afd4
No known key found for this signature in database
GPG Key ID: E28D7679E9A9EDE2
4 changed files with 259 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
templates/docs/self_hosted.html
View File

@ -59,11 +59,9 @@ $ ./manage.py migrate
$ ./manage.py createsuperuser
</code></pre></div>
</li>
</ul>
<p>With the default configuration, Healthchecks stores data in a SQLite file
<code>hc.sqlite</code> in the checkout directory (<code>~/webapps/healthchecks</code>).</p>
<ul>
<code>hc.sqlite</code> in the checkout directory (<code>~/webapps/healthchecks</code>).</p>
</li>
<li>
<p>Run tests:</p>
<div class="highlight"><pre><span></span><code>$ ./manage.py <span class="nb">test</span>
@ -75,12 +73,100 @@ $ ./manage.py createsuperuser
<div class="highlight"><pre><span></span><code>$ ./manage.py runserver
</code></pre></div>
</li>
<li>
<p>From another shell, run the <code>sendalerts</code> management command, responsible for
sending out notifications:</p>
<div class="highlight"><pre><span></span><code>$ ./manage.py sendalerts
</code></pre></div>
</li>
</ul>
<p>At this point, the site should now be running at <code>http://localhost:8000</code>.</p>
<p>To access Django administration site, log in as a superuser, then
visit <code>http://localhost:8000/admin/</code>.</p>
<p>FIXME note about no email configuration, no sendalerts, and the devserver</p>
<h2>Accessing Administration Panel</h2>
<p>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:</p>
<div class="highlight"><pre><span></span><code>$ ./manage.py createsuperuser
</code></pre></div>
<p>Then, log into the site using the superuser credentials. Once logged in,
click on the "Account" dropdown in top navigation, and select "Site Administration".</p>
<h2>Sending Emails</h2>
<p>Healthchecks needs SMTP credentials to be able to send emails:
login links, monitoring notifications, monthly reports.</p>
<p>Specify SMTP credentials using the <code>EMAIL_HOST</code>, <code>EMAIL_PORT</code>, <code>EMAIL_HOST_USER</code>,
<code>EMAIL_HOST_PASSWORD</code>, and <code>EMAIL_USE_TLS</code> environment variables. Example:</p>
<div class="highlight"><pre><span></span><code><span class="na">EMAIL_HOST</span><span class="o">=</span><span class="s">my-smtp-server-here.com</span>
<span class="na">EMAIL_PORT</span><span class="o">=</span><span class="s">587</span>
<span class="na">EMAIL_HOST_USER</span><span class="o">=</span><span class="s">my-username</span>
<span class="na">EMAIL_HOST_PASSWORD</span><span class="o">=</span><span class="s">mypassword</span>
<span class="na">EMAIL_USE_TLS</span> <span class="o">=</span> <span class="s">True</span>
</code></pre></div>
<p>You can read more about handling outbound email in the Django documentation,
<a href="https://docs.djangoproject.com/en/3.1/topics/email/">Sending Email</a> section.</p>
<h2>Receiving Emails</h2>
<p>Healthchecks comes with a <code>smtpd</code> management command, which starts up a
SMTP listener service. With the command running, you can ping your
checks by sending email messages.</p>
<p>Start the SMTP listener on port 2525:</p>
<div class="highlight"><pre><span></span><code>$ ./manage.py smtpd --port <span class="m">2525</span>
</code></pre></div>
<p>Send a test email:</p>
<div class="highlight"><pre><span></span><code>$ curl --url <span class="s1">&#39;smtp://127.0.0.1:2525&#39;</span> <span class="se">\</span>
--mail-from <span class="s1">&#39;foo@example.org&#39;</span> <span class="se">\</span>
--mail-rcpt <span class="s1">&#39;11111111-1111-1111-1111-111111111111@my-hc.example.org&#39;</span> <span class="se">\</span>
-F <span class="s1">&#39;=&#39;</span>
</code></pre></div>
<h2>Sending Status Notifications</h2>
<p>The <code>sendalerts</code> management command continuously polls the database for any checks
changing state, and sends out notifications as needed.
When <code>sendalerts</code> is not running, the Healthchecks instance will not send out any
alerts.</p>
<p>Within an activated virtualenv, run the <code>sendalerts</code> command like so:</p>
<div class="highlight"><pre><span></span><code>$ ./manage.py sendalerts
</code></pre></div>
<p>In a production setup, make sure the <code>sendalerts</code> command can survive
server restarts.</p>
<h2>Database Cleanup</h2>
<p>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:</p>
<p>Remove old records from the <code>api_ping</code> table. For each check, keep 100 most
recent pings:</p>
<div class="highlight"><pre><span></span><code>$ ./manage.py prunepings
</code></pre></div>
<p>Remove old records of sent notifications. For each check, remove notifications that
are older than the oldest stored ping for the corresponding check.</p>
<div class="highlight"><pre><span></span><code>$ ./manage.py prunenotifications
</code></pre></div>
<p>Remove inactive user accounts:</p>
<div class="highlight"><pre><span></span><code>$ ./manage.py pruneusers
</code></pre></div>
<p>Remove old records from the <code>api_tokenbucket</code> table. The TokenBucket
model is used for rate-limiting login attempts and similar operations.
Any records older than one day can be safely removed.</p>
<div class="highlight"><pre><span></span><code>$ ./manage.py prunetokenbucket
</code></pre></div>
<p>Remove old records from the <code>api_flip</code> 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.</p>
<div class="highlight"><pre><span></span><code>$ ./manage.py pruneflips
</code></pre></div>
<p>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.</p>
<p>In a production setup, you will want to run these commands regularly, as well as
have regular, automatic database backups set up.</p>
<h2>Next Steps</h2>
<p>Get the <a href="https://github.com/healthchecks/healthchecks">source code</a>.</p>
<p>See <a href="../self_hosted_configuration/">Configuration</a> for a list of configuration options.</p>

113
templates/docs/self_hosted.md
View File

@ -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
FIXME note about no email configuration, no sendalerts, and the devserver
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.
In a production setup, you will want to run these commands regularly, as well as
have regular, automatic database backups set up.
## Next Steps

24
templates/docs/self_hosted_configuration.html
View File

@ -22,6 +22,7 @@ integration.</p>
<h2><code>DEBUG</code></h2>
<p>Default: <code>True</code></p>
<p>A boolean that turns on/off debug mode.</p>
<p><em>Never run a Healthchecks instance in production with the debug mode turned on!</em></p>
<p>This is a standard Django setting, read more in
<a href="https://docs.djangoproject.com/en/3.1/ref/settings/#debug">Django documentation</a>.</p>
<h2><code>DEFAULT_FROM_EMAIL</code></h2>
@ -115,6 +116,7 @@ set <code>EMAIL_USE_VERIFICATION</code> to <code>False</code>.</p>
<p>Default: <code>None</code></p>
<h2><code>MASTER_BADGE_LABEL</code></h2>
<p>Default: same as <code>SITE_NAME</code></p>
<p>The label for the "Overall Status" status badge.</p>
<h2><code>MATRIX_ACCESS_TOKEN</code></h2>
<p>Default: <code>None</code></p>
<p>The <a href="https://matrix.org/">Matrix</a> 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 <code>None</code>.</p>
<h2><code>PING_EMAIL_DOMAIN</code></h2>
<p>Default: <code>localhost</code></p>
<p>The domain to use for generating ping email addresses. Example:</p>
<div class="highlight"><pre><span></span><code><span class="na">PING_EMAIL_DOMAIN</span><span class="o">=</span><span class="s">ping.my-hc.example.org</span>
</code></pre></div>
<p>In this example, Healthchecks would generate ping email addresses similar
to <code>3f1a7317-8e96-437c-a17d-b0d550b51e86@ping.my-hc.example.org</code>.</p>
<h2><code>PING_ENDPOINT</code></h2>
<p>Default: <code>http://localhost:8000/ping/</code></p>
<p>Default: <code>{SITE_ROOT}/ping/</code></p>
<p>The base URL to use for generating ping URLs. Example:</p>
<div class="highlight"><pre><span></span><code><span class="na">PING_ENDPOINT</span><span class="o">=</span><span class="s">https://ping.my-hc.example.org</span>
</code></pre></div>
<p>In this example, Healthchecks would generate ping URLs similar
to <code>https://ping.my-hc.example.org/3f1a7317-8e96-437c-a17d-b0d550b51e86</code>.</p>
<h2><code>PUSHBULLET_CLIENT_ID</code></h2>
<p>Default: <code>None</code></p>
<h2><code>PUSHBULLET_CLIENT_SECRET</code></h2>
@ -244,8 +258,12 @@ notifications. Healthcecks interacts with signal-cli over DBus.</p>
</ul>
<h2><code>SITE_ROOT</code></h2>
<p>Default: <code>http://localhost:8000</code></p>
<p>The base URL of this Healthchecks instance. Healthchecks uses <code>SITE_ROOT</code> whenever
it needs to construct absolute URLs.</p>
<h2><code>SITE_NAME</code></h2>
<p>Default: <code>Mychecks</code></p>
<p>The display name of this Healthchecks instance. Healthchecks uses it throughout
web UI and documentation.</p>
<h2><code>SLACK_CLIENT_ID</code></h2>
<p>Default: <code>None</code></p>
<p>The Slack Client ID, required by the Slack integration.</p>
@ -288,6 +306,10 @@ scheme.</p>
<p>The Telegram bot user's authentication token, required by the Telegram integration.</p>
<h2><code>TRELLO_APP_KEY</code></h2>
<p>Default: <code>None</code></p>
<p>The <a href="https://trello.com/">Trello</a> app key, required by the Trello integration.</p>
<p>To set up the Trello integration, get a developer API key from
<a href="https://trello.com/app-key">https://trello.com/app-key</a> and put it in the
<code>TRELLO_APP_KEY</code> environment variable.</p>
<h2><code>TWILIO_ACCOUNT</code></h2>
<p>Default: <code>None</code></p>
<h2><code>TWILIO_AUTH</code></h2>

36
templates/docs/self_hosted_configuration.md
View File

@ -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`