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

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

# install prerequisitessudo apt install apt-transport-https ca-certificates curl software-properties-common gnupg-agent -y# add docker gpg keycurl -fsSL https://download.docker.com/linux/$(awk -F'=' '/^ID=/{ print $NF }' /etc/os-release)/gpg | sudo apt-key add -# add docker software repositorysudo 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 dockersudo apt install docker-ce docker-compose containerd.io -y# enable and start docker servicesudo systemctl enable docker && sudo systemctl start docker# add the current user to the docker groupsudo usermod -aG docker $USER# reauthenticate for the new group membership to take effectsu - $USER

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

2. Create directories, the network, and `.env`

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

# create working directoriesmkdir ~/docker/postresql -p && mkdir ~/docker/healthchecks -p# create containers networkdocker network create containers# download the base configurationwget -O ~/docker/healthchecks/.env https://raw.githubusercontent.com/healthchecks/healthchecks/master/docker/.env.example# generate a 32 character random stringhead /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32# copy the output string to the clipboard# edit the .env filenano ~/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]

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=postgresDB_HOST=postgresDB_NAME=healthchecksDB_PASSWORD=CHANGE_ME_DB_PASSWORDDB_USER=healthchecks_rw---[email protected]---EMAIL_HOST=smtp.i12bretro.localEMAIL_HOST_PASSWORD=EMAIL_HOST_USER=EMAIL_PORT=25EMAIL_USE_TLS=FalseEMAIL_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]

Press CTRL+W and search for localhost.[12]
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]
Press CTRL+O, Enter, CTRL+X to save .env.[12]

3. Run PostgreSQL and Healthchecks

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

# set owner of working directoriessudo chown "$USER":"$USER" ~/docker -R# run the postgresql docker containerdocker 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 containerdocker run -d --name healthchecks --env-file ~/docker/healthchecks/.env -p 8000:8000 --network containers --restart=unless-stopped healthchecks/healthchecks# connect to healthchecks container shelldocker 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 shellexit

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

Open http://DNSorIP:8000.[12]
Log in with the administrator account created above.[12]
Confirm the Healthchecks dashboard.[12]
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

https://www.youtube.com/watch?v=4l57CgiHKRI — official i12bretro video. ↩
https://i12bretro.github.io/tutorials/0813.html — Running Healthchecks - A Cron Job Monitoring Service - In Docker. ↩