Run Healthchecks in Docker: Monitor Cron Jobs with HTTP Pings

Healthchecks receives HTTP requests or email “pings” from cron jobs and alerts when a ping is late. Tutorial 0813 runs Healthchecks with PostgreSQL in Docker, then creates an administrator account on port 8000.[12]

The original i12bretro video remains on YouTube.[17]

1. Install Docker

1. Log into the Linux device.[12]
2. Run:[12]

# install prerequisites
sudo apt install apt-transport-https ca-certificates curl software-properties-common gnupg-agent -y
# add docker gpg key
curl -fsSL https://download.docker.com/linux/$(awk -F'=' '/^ID=/{ print $NF }' /etc/os-release)/gpg | sudo apt-key add -
# add docker software repository
sudo add-apt-repository "deb [arch=$(dpkg --print-architecture)] https://download.docker.com/linux/$(awk -F'=' '/^ID=/{ print $NF }' /etc/os-release) $(lsb_release -cs) stable"
# install docker
sudo apt install docker-ce docker-compose containerd.io -y
# enable and start docker service
sudo systemctl enable docker && sudo systemctl start docker
# add the current user to the docker group
sudo usermod -aG docker $USER
# reauthenticate for the new group membership to take effect
su - $USER

Reauthenticate after the Docker group change and check the daemon.[12]

2. Create directories, the network, and .env

1. Create the working directories and Docker network, download the base configuration, and generate a 32-character random string with these commands.[12]

# create working directories
mkdir ~/docker/postresql -p && mkdir ~/docker/healthchecks -p
# create containers network
docker network create containers
# download the base configuration
wget -O ~/docker/healthchecks/.env https://raw.githubusercontent.com/healthchecks/healthchecks/master/docker/.env.example
# generate a 32 character random string
head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32
# copy the output string to the clipboard
# edit the .env file
nano ~/docker/healthchecks/.env

The postresql path is kept exactly as written in the tutorial. I can choose another spelling locally, but then I change the later volume path consistently.[12]

2. Scroll through .env and update at least these keys.[12]

In .env, scroll through the file and enter your own database, email, and secret-key values:[12]

ALLOWED_HOSTS=*
---
DB=postgres
DB_HOST=postgres
DB_NAME=healthchecks
DB_PASSWORD=CHANGE_ME_DB_PASSWORD
DB_USER=healthchecks_rw
---
DEFAULT_FROM_EMAIL=healthchecks@i12bretro.local
---
EMAIL_HOST=smtp.i12bretro.local
EMAIL_HOST_PASSWORD=
EMAIL_HOST_USER=
EMAIL_PORT=25
EMAIL_USE_TLS=False
EMAIL_USE_VERIFICATION=False
---
SECRET_KEY=<random string from the command above>

ALLOWED_HOSTS=* is the value shown by the source; for a real deployment I consider a specific hostname. SECRET_KEY must be a separate random string and DB_PASSWORD must match the PostgreSQL password.[12]

3. Press CTRL+W and search for localhost.[12]
4. Replace every localhost reference with the Docker host’s DNS name or IP, for example set SITE_ROOT=http://ubuntuser.local:8000 or SITE_ROOT=http://ubuntuserver.local:8000 instead of SITE_ROOT=http://localhost:8000.[12]
5. Press CTRL+O, Enter, CTRL+X to save .env.[12]

3. Run PostgreSQL and Healthchecks

1. After editing .env, run the commands that create PostgreSQL, Healthchecks, and the administrator.[12]

# set owner of working directories
sudo chown "$USER":"$USER" ~/docker -R
# run the postgresql docker container
docker run -d --name postgres -e POSTGRES_USER=healthchecks_rw -e POSTGRES_PASSWORD='CHANGE_ME_DB_PASSWORD' -e POSTGRES_DB=healthchecks -v /home/$USER/docker/postresql:/var/lib/postgresql/data --network containers --restart=unless-stopped postgres
# run the healthchecks container
docker run -d --name healthchecks --env-file ~/docker/healthchecks/.env -p 8000:8000 --network containers --restart=unless-stopped healthchecks/healthchecks
# connect to healthchecks container shell
docker exec -ti healthchecks /bin/bash
# create an admin user
/opt/healthchecks/manage.py createsuperuser
# enter an email address
# enter and confirm a password
# exit the container shell
exit

The PostgreSQL password in the command must match DB_PASSWORD in .env; create a unique password and enter the same value in both places. Enter the admin email and password interactively in createsuperuser.[12]

4. Log in and create a ping

1. Open http://DNSorIP:8000.[12]
2. Log in with the administrator account created above.[12]
3. Confirm the Healthchecks dashboard.[12]
4. Create a check for a cron job and use the ping URL supplied by the dashboard in the real job.[12]

Checks and limits

I inspect docker ps, docker logs postgres, docker logs healthchecks, the database volume, and the containers network. If I change SITE_ROOT, email, or the database password, I restart the container and read its logs rather than guessing. I do not expose PostgreSQL on WAN; the source describes 2FA/WebAuthn and team features, but protecting the dashboard remains a deployment responsibility.[12]

Original tutorial video: [watch it on YouTube]¹.[17]

Source

Original source: [Running Healthchecks - A Cron Job Monitoring Service - In Docker]², published/updated 2024-07-28.[12]

Sources

[12] https://i12bretro.github.io/tutorials/0813.html — Running Healthchecks in Docker [17] https://www.youtube.com/watch?v=4l57CgiHKRI — Running Healthchecks — A Cron Job Monitoring Service — In Docker — i12bretro video