mirror of
https://github.com/healthchecks/healthchecks.git
synced 2024-11-27 01:27:51 +00:00
13f92b90ef
And add it to docs. And add a system check to make sure it, if set, is a tuple with 2 elements. cc: #851
174 lines
9.8 KiB
Plaintext
174 lines
9.8 KiB
Plaintext
<h1>Self-Hosted Healthchecks</h1>
|
|
<p>Healthchecks is open-source, and is licensed under the BSD 3-clause license.</p>
|
|
<p>As an alternative to using the hosted service at
|
|
<a href="https://healthchecks.io">https://healthchecks.io</a>, you have the option to host a
|
|
Healthchecks instance yourself.</p>
|
|
<p>The building blocks are:</p>
|
|
<ul>
|
|
<li>Python 3.10+</li>
|
|
<li>Django 5.1</li>
|
|
<li>PostgreSQL or MySQL</li>
|
|
</ul>
|
|
<h2>Setting Up for Development</h2>
|
|
<p>You can set up a development environment in a Python
|
|
<a href="https://docs.python.org/3/tutorial/venv.html">virtual environment</a>
|
|
on your local system to develop a new feature, write a new integration
|
|
or test a bugfix.</p>
|
|
<p>The following instructions assume you are using a Debian-based OS.</p>
|
|
<ul>
|
|
<li>
|
|
<p>Install dependencies:</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>sudo<span class="w"> </span>apt-get<span class="w"> </span>update
|
|
$<span class="w"> </span>sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>gcc<span class="w"> </span>python3-dev<span class="w"> </span>python3-venv
|
|
</code></pre></div>
|
|
|
|
</li>
|
|
<li>
|
|
<p>Prepare directory for project code and virtualenv. Feel free to use a
|
|
different location:</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>mkdir<span class="w"> </span>-p<span class="w"> </span>~/webapps
|
|
$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>~/webapps
|
|
</code></pre></div>
|
|
|
|
</li>
|
|
<li>
|
|
<p>Prepare virtual environment
|
|
(with virtualenv you get pip, we'll use it soon to install requirements):</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>python3<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>hc-venv
|
|
$<span class="w"> </span><span class="nb">source</span><span class="w"> </span>hc-venv/bin/activate
|
|
</code></pre></div>
|
|
|
|
</li>
|
|
<li>
|
|
<p>Check out project code:</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/healthchecks/healthchecks.git
|
|
</code></pre></div>
|
|
|
|
</li>
|
|
<li>
|
|
<p>Install requirements (Django, ...) into virtualenv:</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>wheel
|
|
$<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>healthchecks/requirements.txt
|
|
</code></pre></div>
|
|
|
|
</li>
|
|
<li>
|
|
<p>Create database tables and a superuser account:</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>~/webapps/healthchecks
|
|
$<span class="w"> </span>./manage.py<span class="w"> </span>migrate
|
|
$<span class="w"> </span>./manage.py<span class="w"> </span>createsuperuser
|
|
</code></pre></div>
|
|
|
|
<p>With the default configuration, Healthchecks stores data in a SQLite file
|
|
<code>hc.sqlite</code> in the project directory (<code>~/webapps/healthchecks/</code>).</p>
|
|
</li>
|
|
<li>
|
|
<p>Run tests:</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>./manage.py<span class="w"> </span><span class="nb">test</span>
|
|
</code></pre></div>
|
|
|
|
</li>
|
|
<li>
|
|
<p>Run development server:</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>./manage.py<span class="w"> </span>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>$<span class="w"> </span>./manage.py<span class="w"> </span>sendalerts
|
|
</code></pre></div>
|
|
|
|
</li>
|
|
</ul>
|
|
<p>At this point, the site should now be running at <code>http://localhost:8000</code>.</p>
|
|
<h2>Accessing Administration Panel</h2>
|
|
<p>Healthchecks comes with Django's administration panel where you can perform
|
|
administrative tasks: delete user accounts, change passwords, increase limits for
|
|
specific users, inspect contents of database tables.</p>
|
|
<p>To access the administration panel, if you haven't already, create a superuser account:</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>./manage.py<span class="w"> </span>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>, <code>EMAIL_USE_SSL</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">465</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_SSL</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">True</span>
|
|
<span class="na">EMAIL_USE_TLS</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">False</span>
|
|
</code></pre></div>
|
|
|
|
<p>You can read more about handling outbound email in the Django documentation,
|
|
<a href="https://docs.djangoproject.com/en/4.2/topics/email/">Sending Email</a> section.</p>
|
|
<h2>Receiving Emails</h2>
|
|
<p>Healthchecks comes with a <code>smtpd</code> management command, which starts up an
|
|
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>$<span class="w"> </span>./manage.py<span class="w"> </span>smtpd<span class="w"> </span>--port<span class="w"> </span><span class="m">2525</span>
|
|
</code></pre></div>
|
|
|
|
<p>Send a test email:</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>curl<span class="w"> </span>--url<span class="w"> </span><span class="s1">'smtp://127.0.0.1:2525'</span><span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--mail-from<span class="w"> </span><span class="s1">'foo@example.org'</span><span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--mail-rcpt<span class="w"> </span><span class="s1">'11111111-1111-1111-1111-111111111111@my-hc.example.org'</span><span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>-F<span class="w"> </span><span class="s1">'='</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>$<span class="w"> </span>./manage.py<span class="w"> </span>sendalerts
|
|
</code></pre></div>
|
|
|
|
<p>In a production setup, make sure the <code>sendalerts</code> command can survive
|
|
server restarts.</p>
|
|
<h2 id="database-cleanup">Database Cleanup</h2>
|
|
<p>Healthchecks deletes old entries from <code>api_ping</code>, <code>api_flip</code>, and <code>api_notification</code>
|
|
tables automatically. By default, Healthchecks keeps the 100 most recent
|
|
pings for every check. You can set the limit higher to keep a longer history:
|
|
go to the Administration Panel, look up user's <strong>Profile</strong> and modify its
|
|
"Ping log limit" field.</p>
|
|
<p>Healthchecks provides management commands for cleaning up
|
|
<code>auth_user</code> (user accounts) and <code>api_tokenbucket</code> (rate limiting records) tables,
|
|
and for removing stale objects from external object storage.</p>
|
|
<p>Remove user accounts that are older than 1 month and have never logged in:</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>./manage.py<span class="w"> </span>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>$<span class="w"> </span>./manage.py<span class="w"> </span>prunetokenbucket
|
|
</code></pre></div>
|
|
|
|
<p>Remove old objects from external object storage. When an user removes
|
|
a check, removes a project, or closes their account, Healthchecks
|
|
does not remove the associated objects from the external object
|
|
storage on the fly. Instead, you should run <code>pruneobjects</code> occasionally
|
|
(for example, once a month). This command first takes an inventory
|
|
of all checks in the database, and then iterates over top-level
|
|
keys in the object storage bucket, and deletes any that don't also
|
|
exist in the database.</p>
|
|
<div class="highlight"><pre><span></span><code>$<span class="w"> </span>./manage.py<span class="w"> </span>pruneobjects
|
|
</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, not on the live database right away.
|
|
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> |