The most straightforward supported deployment is Docker Compose on a Linux VPS: run Healthchecks in the official web container, connect it to PostgreSQL (managed or on the same host), and put a TLS-terminating reverse proxy such as Caddy or NGINX in front. You need a DNS name, Docker Engine with Compose, working SMTP credentials, and a tested plan for persistent database backups.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
This guide covers the complete path from an empty VPS to a secured administrator login, then explains database layouts, proxy headers, upgrades, and the failure modes that commonly make an otherwise healthy container return errors.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
What a self-hosted Healthchecks installation contains
Healthchecks is a web application that receives periodic “I am alive” pings from cron jobs, scheduled tasks, and other automation. A production installation is more than one HTTP process: it needs application settings, a database, background workers, and a front end that handles HTTPS.
| Component | Role | Where it can run |
|---|---|---|
| Healthchecks web container | Serves the dashboard and API, applies migrations at startup, and runs the uWSGI application server. | Docker on your VPS |
| Database | Stores users, checks, ping history, schedules, and configuration. | SQLite, PostgreSQL, or MySQL; PostgreSQL may be on the VPS or managed separately. |
| Alert, report, and SMTP workers | Processes check state changes, scheduled reports, and outgoing mail. | Started by the reference container setup. |
| TLS reverse proxy | Obtains and renews certificates, accepts public HTTPS traffic, and forwards requests to the web container. | Caddy, NGINX, a load balancer, or another controlled proxy. |
| Persistent storage and backups | Protects the database from host failure, accidental deletion, and upgrade mistakes. | Docker volume plus an off-server copy. |
The pre-built image supports amd64, arm/v7, and arm64. It does not terminate TLS, so an Internet-facing instance must have a proxy or load balancer in front of it.
#1 Best Overall
- Includes Raspberry Pi 5 with 2.4Ghz 64-bit quad-core CPU (8GB RAM)
- Includes 128GB Micro SD Card pre-loaded with 64-bit Raspberry Pi OS, USB MicroSD Card Reader
- CanaKit Turbine Black Case for the Raspberry Pi 5
- CanaKit Low Noise Bearing System Fan
- Mega Heat Sink - Black Anodized
Prerequisites and sensible planning
DNS and a Linux host
Choose a DNS name such as health.example.net and point its A or AAAA record at the VPS before requesting a certificate. The host must be able to accept inbound connections on the ports used by your reverse proxy, normally TCP 80 and 443. Keep the application and database on a private Docker network; expose only the proxy to the public Internet.
Software and credentials
- A current Linux VPS with Docker Engine and Docker Compose support.
- An SMTP account that permits the server to send alert and administrative mail.
- A method for retaining database backups somewhere other than the VPS.
- Shell access with permission to run Docker commands.
The official material does not publish a universal CPU or RAM minimum. Size the host from the number of checks and their retention period, worker activity, database placement, and any other services sharing the machine. A small personal installation and a high-volume monitoring service should not be sized from the same rule of thumb.
Required application settings
Healthchecks’ Docker configuration expects these values in its environment file:
| Variable | Purpose | Operational guidance |
|---|---|---|
ALLOWED_HOSTS |
Lists host names accepted by the application. | Include the exact DNS name users will visit; do not use a broad wildcard unnecessarily. |
DEFAULT_FROM_EMAIL |
Sender address used for application mail. | Use an address permitted by your SMTP provider. |
EMAIL_HOST |
SMTP server name. | Use the provider’s documented hostname. |
EMAIL_HOST_USER and EMAIL_HOST_PASSWORD |
SMTP authentication. | Store the password only in the protected environment file or secret store. |
SECRET_KEY |
Cryptographic signing key for the application. | Generate a unique, unpredictable value; never copy a public example or reuse a key from another installation. |
SITE_ROOT |
Canonical public URL. | Set it to the final HTTPS URL, including the scheme. |
Choose the database layout before installing
Healthchecks supports SQLite, PostgreSQL, and MySQL. The choice is primarily an operations decision rather than a feature switch.
| Layout | Advantages | Costs and responsibilities | Good fit |
|---|---|---|---|
| SQLite on the VPS | Fewest moving parts and simplest single-host setup. | Backups, file durability, and concurrency are your responsibility; moving the database to another host later requires a migration plan. | Small, single-server installations with modest check volume. |
| PostgreSQL container on the VPS | Both services can be described in one Compose project and backed up together. | You maintain the database container, volume, upgrades, monitoring, and recovery. | Operators who want a self-contained stack. |
| Managed PostgreSQL | Database maintenance, durability options, and often automated backups are handled by the provider. | Additional recurring cost, network connectivity requirements, and provider-specific restore procedures. | The official VPS walkthrough’s architecture, or any installation where separating failure domains matters. |
| MySQL | Supported by the application and familiar to teams already operating it. | You still need a managed or self-managed service and a tested backup process. | Existing MySQL operations environments. |
Do not choose a database solely because it is present in a sample file. Decide who will perform backups, who can restore after corruption, and whether the database should survive a complete VPS loss. A same-host database is operationally convenient; a managed database reduces host-level work but introduces a network dependency.
Install Healthchecks with Docker Compose
1. Obtain the application configuration
Use the Healthchecks source tree or a release configuration that contains the official Docker files. Keep the files in a dedicated directory owned by an administrator account, and review the image tag before every upgrade rather than silently following an unreviewed moving tag.
Rank #2
- Includes Raspberry Pi 5 with 2.4Ghz 64-bit quad-core CPU (4GB RAM)
- Includes 128GB Micro SD Card pre-loaded with 64-bit Raspberry Pi OS, USB MicroSD Card Reader
- CanaKit Turbine Black Case for the Raspberry Pi 5
- CanaKit Low Noise Bearing System Fan
- CanaKit Mega Heat Sink - Black Anodized
2. Create the environment file
From the project directory, copy the supplied template:
cp docker/.env.example docker/.envEdit docker/.env and set every required value. Generate the secret key with a cryptographically secure method available on your system; for example, a local password manager or a secure random generator. The exact value must never be committed to a public repository, pasted into a support forum, or shared between unrelated Healthchecks instances.
Set SITE_ROOT and ALLOWED_HOSTS to the DNS name you actually configured. If you later change the public hostname, update both the DNS and application settings together so redirects, cookies, and host validation agree.
3. Start the Compose project
Change into the Docker directory and start the services:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →cd docker
docker compose upFor a server intended to stay online after you disconnect, run the project in detached mode according to your Compose version. Watch the initial output for database connectivity, migration completion, and worker startup. The reference image applies database migrations at startup and launches the alert, report, and SMTP workers in the container.
4. Create the first administrator
After the web service and database are available, create an administrator account:
Rank #3
- CanaKit Raspberry Pi 5 Essentials Starter Kit
docker compose run web /opt/healthchecks/manage.py createsuperuserAnswer the prompts with a long, unique password. This command runs the management script in the Compose project, so execute it from the directory containing the project’s Compose file.
5. Sign in and verify the basics
Open the configured HTTPS address and sign in. Create a disposable check and send a test ping from a system that can reach the public URL. Confirm that the check changes state, that an alert can be delivered through SMTP, and that the administrator can sign out and back in. A successful page load alone does not prove that workers, mail, or the database are functioning.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Put HTTPS and the reverse proxy in front
Why the proxy is mandatory for public exposure
The Docker image serves the application but does not terminate TLS. Place Caddy, NGINX, or another controlled TLS proxy in front of it. The proxy should obtain a certificate for the DNS name, redirect plain HTTP to HTTPS, and forward traffic to the private web service over the Docker network or a restricted local port.
Set forwarding headers safely
Healthchecks uses proxy headers to detect secure requests and to apply IP-based rate limiting. The proxy must discard any client-supplied X-Forwarded-Proto, replace it with the original scheme (https for an HTTPS request), and set X-Forwarded-For to the client address. Do not blindly pass these headers from an untrusted Internet client.
If another load balancer sits in front of your proxy, define which hop is trusted and preserve the real client address according to that product’s documented chain format. A malformed chain can make every request appear to originate from one proxy or can let a client spoof its scheme.
Recognize proxy-related failures
- An HTTP 403 CSRF error on an otherwise valid HTTPS form submission often means
X-Forwarded-Protois wrong or being overwritten. - Unexpected host validation errors usually indicate that the requested DNS name is missing from
ALLOWED_HOSTS. - Certificate issuance failures generally mean DNS is not pointing at the VPS or the proxy’s public ports are blocked.
Fix the proxy configuration first, then retry in a fresh browser session so an old redirect or cookie does not conceal the result.
Rank #4
- Includes Raspberry Pi 5 16GB with 2.4Ghz 64-bit quad-core CPU (16GB RAM)
- Includes 128GB Micro SD Card pre-loaded with 64-bit Raspberry Pi OS, USB MicroSD Card Reader
- CanaKit Turbine Black Case for the Raspberry Pi 5
- CanaKit Low Noise Bearing System Fan
- Mega Heat Sink - Black Anodized
Configure SMTP for alerts and administration
Enter the SMTP host, user, password, and default sender in the environment file before relying on Healthchecks for notifications. Use a sender address authorized by the mail service and check whether the provider requires TLS, a specific port, or an application password. Those transport details vary by provider and are not supplied by Healthchecks itself.
Send a test alert after installation. If the web interface works but mail does not, inspect the container logs for authentication or connection errors, verify outbound SMTP is allowed by the VPS network, and confirm that the sender domain has the required DNS authentication records. Avoid “fixing” delivery by disabling authentication or exposing SMTP credentials in a public Compose file.
Back up the database and prepare for PostgreSQL upgrades
What must be backed up
The database contains the information that makes the service useful: accounts, checks, schedules, state history, and settings. A Docker volume is persistence, not a backup. Keep a recoverable database dump or provider backup outside the VPS, protect it as sensitive data, and periodically perform a restore rehearsal on an isolated system.
Upgrade sequence for a PostgreSQL image change
PostgreSQL major versions require a data-directory upgrade; changing an image tag without upgrading the data directory can leave the database unable to start. Follow this order:
- Take and verify a full database backup before changing any PostgreSQL image version. Record where the copy is stored and how it was validated.
- Stop the
dbandwebcontainers so no process writes to the old data directory. - Identify the Docker volume that contains PostgreSQL’s data and confirm that it is the volume you intend to upgrade.
- Run the documented PostgreSQL data-directory upgrade procedure for the source and target versions. Do not substitute an arbitrary filesystem copy for the upgrade tool’s procedure.
- Update the PostgreSQL image tag in the Compose configuration, keeping the tag pinned to the reviewed release.
- Start the stack, watch the database and web logs, and verify that migrations complete and the administrator can sign in.
- Send a test ping and alert, then retain the pre-upgrade backup until the new instance has passed your recovery checks.
The full backup belongs at the beginning of this sequence, not after the new container starts. If the upgrade fails, stop the services and restore the original data directory or backup rather than repeatedly starting containers against a partially converted directory.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Security and day-to-day operations
- Protect the secret key. Treat it like an application signing secret. Restrict permissions on
docker/.envand rotate it only with a planned session and token impact assessment. - Keep the database private. Do not publish PostgreSQL or MySQL ports to the Internet when the web container can reach the database on an internal network.
- Use controlled HTTPS. Renew certificates automatically, monitor renewal failures, and redirect HTTP rather than leaving users to choose an insecure scheme.
- Validate proxy identity. Trust forwarding headers only from the proxy or load balancer you operate.
- Pin image tags. Review release notes and image changes before upgrading; current tags change over time.
- Monitor workers as well as the web page. A dashboard that loads can coexist with stopped alert or SMTP workers.
- Test recovery. A backup that has never been restored is an assumption, not a recovery plan.
Choose between common deployment variants
| Decision | Option A | Option B | Choose based on |
|---|---|---|---|
| Database location | PostgreSQL or SQLite on the VPS | Managed PostgreSQL | Whether you prefer one-host simplicity or an independent database failure domain. |
| TLS termination | Caddy | NGINX or an existing load balancer | Which proxy your team already patches, monitors, and can configure with correct forwarding headers. |
| Backup responsibility | Local volume plus your own off-site dumps | Managed backups plus your own export | Who owns retention, encryption, restore testing, and incident response. |
| Host usage | Dedicated VPS | Shared VPS with other services | Whether resource spikes, maintenance, or a compromise in another service could affect monitoring. |
| Expected check volume | Single-host database and workers | Separated database and more deliberate capacity planning | Check frequency, retention, worker load, and the consequences of delayed alerts. |
There is no official universal performance benchmark or minimum resource profile to decide these choices for every installation. Start with the simplest topology that meets your recovery and availability requirements, then measure database growth, worker backlog, and host utilization as real check traffic accumulates.
Best Value
- Includes Raspberry Pi 5 with 2.4Ghz 64-bit quad-core CPU (8GB RAM)
- Includes 32GB EVO+ Micro SD Card pre-loaded with 64-bit Pi OS, USB MicroSD Card Reader
- CanaKit Turbine Black Case for the Raspberry Pi 5
- CanaKit 45W PD Power Supply for the Raspberry Pi 5
- Display Cable - 6 foot (Supports up to 4K 60p)
Troubleshooting checklist
The containers stop during startup
Read the Compose output rather than restarting repeatedly. A missing environment value, invalid database credentials, unreachable managed database, or a failed migration will normally be visible in the web or database logs. Correct the underlying setting, then start the project again.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallThe site redirects incorrectly or reports CSRF failures
Confirm that SITE_ROOT uses the public HTTPS URL and that the proxy sets, rather than forwards, X-Forwarded-Proto. Clear stale cookies after correcting the scheme and test a new login.
Healthchecks rejects the hostname
Compare the browser’s hostname with ALLOWED_HOSTS, including subdomains and spelling. DNS, the certificate name, the proxy’s host routing, and this application setting must all refer to the same public name.
Checks appear, but no alert arrives
Verify SMTP credentials, sender permissions, outbound network access, and worker logs. Confirm the check’s notification rules and trigger a deliberate test event instead of waiting for a production failure.
A PostgreSQL upgrade will not start
Do not delete the volume or keep changing tags at random. Stop the stack, preserve the original volume, locate the verified pre-upgrade backup, and repeat the documented data-directory upgrade with matching source and target versions. If recovery is urgent, restore the known-good backup to a separate instance and validate it before repointing the application.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsQuick Recap
A practical maintenance routine
- Review Healthchecks and base-image releases before applying an image update.
- Read the release notes and confirm that the planned database change does not require a major-version data-directory conversion.
- Take a fresh, restorable database backup and record its location.
- Apply the update during a period when delayed checks and alerts are acceptable.
- Check web access, administrator login, a test ping, alert delivery, worker activity, and database logs.
- Keep the rollback copy until those checks pass and your normal retention policy has captured the new state.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
