You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

171 lines
7.7 KiB

  1. <h1>Self-Hosted Healthchecks</h1>
  2. <p>Healthchecks is open-source, and is licensed under the BSD 3-clause license.</p>
  3. <p>As an alternative to using the hosted service at
  4. <a href="https://healthchecks.io">https://healthchecks.io</a>, you have the option to host a
  5. Healthchecks instance yourself.</p>
  6. <p>The building blocks are:</p>
  7. <ul>
  8. <li>Python 3.6+</li>
  9. <li>Django 3</li>
  10. <li>PostgreSQL or MySQL</li>
  11. </ul>
  12. <h2>Setting Up for Development</h2>
  13. <p>You can set up a development environment in a Python
  14. <a href="https://docs.python.org/3/tutorial/venv.html">virtual environment</a>
  15. on your local system to develop a new feature, write a new integration
  16. or test a bugfix.</p>
  17. <p>The following instructions assume you are using a Debian-based OS.</p>
  18. <ul>
  19. <li>
  20. <p>Install dependencies:</p>
  21. <div class="highlight"><pre><span></span><code>$ sudo apt-get update
  22. $ sudo apt-get install -y gcc python3-dev python3-venv
  23. </code></pre></div>
  24. </li>
  25. <li>
  26. <p>Prepare directory for project code and virtualenv. Feel free to use a
  27. different location:</p>
  28. <div class="highlight"><pre><span></span><code>$ mkdir -p ~/webapps
  29. $ <span class="nb">cd</span> ~/webapps
  30. </code></pre></div>
  31. </li>
  32. <li>
  33. <p>Prepare virtual environment
  34. (with virtualenv you get pip, we'll use it soon to install requirements):</p>
  35. <div class="highlight"><pre><span></span><code>$ python3 -m venv hc-venv
  36. $ <span class="nb">source</span> hc-venv/bin/activate
  37. </code></pre></div>
  38. </li>
  39. <li>
  40. <p>Check out project code:</p>
  41. <div class="highlight"><pre><span></span><code>$ git clone https://github.com/healthchecks/healthchecks.git
  42. </code></pre></div>
  43. </li>
  44. <li>
  45. <p>Install requirements (Django, ...) into virtualenv:</p>
  46. <div class="highlight"><pre><span></span><code>$ pip install wheel
  47. $ pip install -r healthchecks/requirements.txt
  48. </code></pre></div>
  49. </li>
  50. <li>
  51. <p>Create database tables and a superuser account:</p>
  52. <div class="highlight"><pre><span></span><code>$ <span class="nb">cd</span> ~/webapps/healthchecks
  53. $ ./manage.py migrate
  54. $ ./manage.py createsuperuser
  55. </code></pre></div>
  56. <p>With the default configuration, Healthchecks stores data in a SQLite file
  57. <code>hc.sqlite</code> in the project directory (<code>~/webapps/healthchecks/</code>).</p>
  58. </li>
  59. <li>
  60. <p>Run tests:</p>
  61. <div class="highlight"><pre><span></span><code>$ ./manage.py <span class="nb">test</span>
  62. </code></pre></div>
  63. </li>
  64. <li>
  65. <p>Run development server:</p>
  66. <div class="highlight"><pre><span></span><code>$ ./manage.py runserver
  67. </code></pre></div>
  68. </li>
  69. <li>
  70. <p>From another shell, run the <code>sendalerts</code> management command, responsible for
  71. sending out notifications:</p>
  72. <div class="highlight"><pre><span></span><code>$ ./manage.py sendalerts
  73. </code></pre></div>
  74. </li>
  75. </ul>
  76. <p>At this point, the site should now be running at <code>http://localhost:8000</code>.</p>
  77. <h2>Accessing Administration Panel</h2>
  78. <p>Healthchecks comes with Django's administration panel where you can manually
  79. view and modify user accounts, projects, checks, integrations etc. To access it,
  80. if you haven't already, create a superuser account:</p>
  81. <div class="highlight"><pre><span></span><code>$ ./manage.py createsuperuser
  82. </code></pre></div>
  83. <p>Then, log into the site using the superuser credentials. Once logged in,
  84. click on the "Account" dropdown in top navigation, and select "Site Administration".</p>
  85. <h2>Sending Emails</h2>
  86. <p>Healthchecks needs SMTP credentials to be able to send emails:
  87. login links, monitoring notifications, monthly reports.</p>
  88. <p>Specify SMTP credentials using the <code>EMAIL_HOST</code>, <code>EMAIL_PORT</code>, <code>EMAIL_HOST_USER</code>,
  89. <code>EMAIL_HOST_PASSWORD</code>, and <code>EMAIL_USE_TLS</code> environment variables. Example:</p>
  90. <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>
  91. <span class="na">EMAIL_PORT</span><span class="o">=</span><span class="s">587</span>
  92. <span class="na">EMAIL_HOST_USER</span><span class="o">=</span><span class="s">my-username</span>
  93. <span class="na">EMAIL_HOST_PASSWORD</span><span class="o">=</span><span class="s">mypassword</span>
  94. <span class="na">EMAIL_USE_TLS</span> <span class="o">=</span> <span class="s">True</span>
  95. </code></pre></div>
  96. <p>You can read more about handling outbound email in the Django documentation,
  97. <a href="https://docs.djangoproject.com/en/3.1/topics/email/">Sending Email</a> section.</p>
  98. <h2>Receiving Emails</h2>
  99. <p>Healthchecks comes with a <code>smtpd</code> management command, which starts up a
  100. SMTP listener service. With the command running, you can ping your
  101. checks by sending email messages.</p>
  102. <p>Start the SMTP listener on port 2525:</p>
  103. <div class="highlight"><pre><span></span><code>$ ./manage.py smtpd --port <span class="m">2525</span>
  104. </code></pre></div>
  105. <p>Send a test email:</p>
  106. <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>
  107. --mail-from <span class="s1">&#39;[email protected]&#39;</span> <span class="se">\</span>
  108. --mail-rcpt <span class="s1">&#39;[email protected]&#39;</span> <span class="se">\</span>
  109. -F <span class="s1">&#39;=&#39;</span>
  110. </code></pre></div>
  111. <h2>Sending Status Notifications</h2>
  112. <p>The <code>sendalerts</code> management command continuously polls the database for any checks
  113. changing state, and sends out notifications as needed.
  114. When <code>sendalerts</code> is not running, the Healthchecks instance will not send out any
  115. alerts.</p>
  116. <p>Within an activated virtualenv, run the <code>sendalerts</code> command like so:</p>
  117. <div class="highlight"><pre><span></span><code>$ ./manage.py sendalerts
  118. </code></pre></div>
  119. <p>In a production setup, make sure the <code>sendalerts</code> command can survive
  120. server restarts.</p>
  121. <h2>Database Cleanup</h2>
  122. <p>With time and use the Healthchecks database will grow in size. You may
  123. decide to prune old data: inactive user accounts, old checks not assigned
  124. to users, old records of outgoing email messages and old records of received pings.
  125. There are separate Django management commands for each task:</p>
  126. <p>Remove old records from the <code>api_ping</code> table. For each check, keep 100 most
  127. recent pings:</p>
  128. <div class="highlight"><pre><span></span><code>$ ./manage.py prunepings
  129. </code></pre></div>
  130. <p>Remove old records of sent notifications. For each check, remove notifications that
  131. are older than the oldest stored ping for the corresponding check.</p>
  132. <div class="highlight"><pre><span></span><code>$ ./manage.py prunenotifications
  133. </code></pre></div>
  134. <p>Remove inactive user accounts:</p>
  135. <div class="highlight"><pre><span></span><code>$ ./manage.py pruneusers
  136. </code></pre></div>
  137. <p>Remove old records from the <code>api_tokenbucket</code> table. The TokenBucket
  138. model is used for rate-limiting login attempts and similar operations.
  139. Any records older than one day can be safely removed.</p>
  140. <div class="highlight"><pre><span></span><code>$ ./manage.py prunetokenbucket
  141. </code></pre></div>
  142. <p>Remove old records from the <code>api_flip</code> table. The Flip objects are used to track
  143. status changes of checks, and to calculate downtime statistics month by month.
  144. Flip objects from more than 3 months ago are not used and can be safely removed.</p>
  145. <div class="highlight"><pre><span></span><code>$ ./manage.py pruneflips
  146. </code></pre></div>
  147. <p>When you first try these commands on your data, it is a good idea to
  148. test them on a copy of your database, and not on the live system.</p>
  149. <p>In a production setup, you will want to run these commands regularly, as well as
  150. have regular, automatic database backups set up.</p>
  151. <h2>Next Steps</h2>
  152. <p>Get the <a href="https://github.com/healthchecks/healthchecks">source code</a>.</p>
  153. <p>See <a href="../self_hosted_configuration/">Configuration</a> for a list of configuration options.</p>