Add more content from README

templates/docs/self_hosted.html

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

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 '[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
 

templates/docs/self_hosted_configuration.html

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

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