nielsperetzke
/
healthchecks
1
0
Fork 0
Code Issues 0 Pull Requests 0 Projects 0 Releases 32 Wiki Activity
Browse Source

Add more content from README

pull/470/head
Pēteris Caune 4 years ago
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
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +93
    -7
      templates/docs/self_hosted.html
  2. +108
    -5
      templates/docs/self_hosted.md
  3. +23
    -1
      templates/docs/self_hosted_configuration.html
  4. +35
    -1
      templates/docs/self_hosted_configuration.md

+ 93
- 7
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;[email protected]&#39;</span> <span class="se">\</span>
--mail-rcpt <span class="s1">&#39;[email protected]&#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>

+ 108
- 5
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
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 '[email protected]' \
--mail-rcpt '[email protected]' \
-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


+ 23
- 1
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>[email protected]</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>


+ 35
- 1
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 `[email protected]`.
## `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`


Write Preview
Loading…
Cancel
Save