This guide provides a complete Ansible playbook to install Healthchecks using the official Docker image with proper configuration for cron job monitoring, alerts, and integrations.
Current Healthchecks version: 3.8 (Docker image)
Create a file named healthchecks.yml:
---
- name: Install and Configure Healthchecks
hosts: healthchecks
become: true
vars:
healthchecks_version: "latest"
healthchecks_port: 8000
healthchecks_domain: "hc.example.com"
healthchecks_secret_key: "CHANGE-ME-TO-A-RANDOM-SECRET-KEY"
healthchecks_email_host: "smtp.example.com"
healthchecks_email_port: 587
healthchecks_email_user: "healthchecks@example.com"
healthchecks_email_password: "smtp_password"
healthchecks_data_dir: "/opt/healthchecks/data"
healthchecks_config_dir: "/opt/healthchecks/config"
tasks:
- name: Install Docker prerequisites
package:
name:
- docker.io
- docker-compose
state: present
when: ansible_os_family == "Debian"
- name: Create Healthchecks directories
file:
path: "{{ item }}"
state: directory
owner: root
group: root
mode: '0755'
loop:
- "{{ healthchecks_data_dir }}"
- "{{ healthchecks_config_dir }}"
- name: Create Healthchecks configuration
copy:
dest: "{{ healthchecks_config_dir }}/env.conf"
owner: root
group: root
mode: '0640'
content: |
# Healthchecks Configuration
# Database settings
DB=sqlite:{{ healthchecks_data_dir }}/hc.sqlite
# Secret key for signing
SECRET_KEY={{ healthchecks_secret_key }}
# Site settings
SITE_ROOT=http://{{ healthchecks_domain }}:{{ healthchecks_port }}
SITE_NAME=Healthchecks
SITE_LOGO_URL=/static/img/logo.png
# Email settings
EMAIL_HOST={{ healthchecks_email_host }}
EMAIL_PORT={{ healthchecks_email_port }}
EMAIL_HOST_USER={{ healthchecks_email_user }}
EMAIL_HOST_PASSWORD={{ healthchecks_email_password }}
EMAIL_USE_TLS=True
DEFAULT_FROM_EMAIL={{ healthchecks_email_user }}
# Security settings
ALLOWED_HOSTS=*
CSRF_TRUSTED_ORIGINS=http://{{ healthchecks_domain }}:{{ healthchecks_port }}
# Integration settings
USE_PAYMENTS=False
REGISTRATION_OPEN=True
# Alert settings
PING_ENDPOINT={{ healthchecks_domain }}/ping/
PING_EMAIL_DOMAIN={{ healthchecks_domain }}
- name: Create Docker Compose file
copy:
dest: "{{ healthchecks_data_dir }}/docker-compose.yml"
owner: root
group: root
mode: '0644'
content: |
version: '3.8'
services:
healthchecks:
image: linuxserver/healthchecks:{{ healthchecks_version }}
container_name: healthchecks
restart: unless-stopped
ports:
- "{{ healthchecks_port }}:8000"
volumes:
- {{ healthchecks_data_dir }}/config:/config
- {{ healthchecks_data_dir }}/data:/data
env_file:
- {{ healthchecks_config_dir }}/env.conf
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
networks:
- healthchecks_net
networks:
healthchecks_net:
driver: bridge
- name: Start Healthchecks container
community.docker.docker_compose:
project_src: "{{ healthchecks_data_dir }}"
state: present
build: false
pull: true
- name: Wait for Healthchecks to start
wait_for:
port: "{{ healthchecks_port }}"
delay: 5
timeout: 120
- name: Configure firewall (UFW)
ufw:
rule: allow
port: "{{ healthchecks_port }}"
proto: tcp
comment: "Healthchecks web interface"
when: ansible_os_family == "Debian"
failed_when: false
- name: Configure firewall (firewalld)
firewalld:
port: "{{ healthchecks_port }}/tcp"
permanent: true
immediate: true
state: enabled
when: ansible_os_family == "RedHat"
failed_when: false
- name: Verify Healthchecks is running
uri:
url: "http://localhost:{{ healthchecks_port }}/accounts/login/"
method: GET
status_code: 200
register: health_check
retries: 3
delay: 5
until: health_check.status == 200
- name: Display Healthchecks status
debug:
msg: |
Healthchecks {{ healthchecks_version }} installed successfully!
Web Interface: http://{{ ansible_default_ipv4.address | default(ansible_host) }}:{{ healthchecks_port }}
Data directory: {{ healthchecks_data_dir }}
Config directory: {{ healthchecks_config_dir }}
IMPORTANT: Create your admin account on first login!
---
healthchecks:
hosts:
healthchecks-server:
ansible_host: 192.168.1.112
ansible_user: ansible
ansible_become: true
# Test connectivity
ansible all -i inventory.yml -m ping
# Run the Healthchecks playbook
ansible-playbook -i inventory.yml healthchecks.yml
# Run with custom settings
ansible-playbook -i inventory.yml healthchecks.yml \
-e "healthchecks_domain=hc.example.com" \
-e "healthchecks_secret_key=$(openssl rand -base64 32)"
# Check container status
ssh healthchecks-server "docker ps | grep healthchecks"
# View container logs
ssh healthchecks-server "docker logs healthchecks"
# Test web interface
curl -I http://healthchecks-server:8000
# Access web UI
# http://healthchecks-server:8000
- name: Create Healthchecks admin user
hosts: healthchecks
become: true
vars:
healthchecks_data_dir: "/opt/healthchecks/data"
admin_email: "admin@example.com"
admin_password: "AdminP@ss123"
tasks:
- name: Create superuser
community.docker.docker_container_exec:
container: healthchecks
command: >
python manage.py createsuperuser
--noinput
--email {{ admin_email }}
environment:
DJANGO_SUPERUSER_PASSWORD: "{{ admin_password }}"
register: result
failed_when: false
- name: Display admin credentials
debug:
msg: |
Admin user created!
Email: {{ admin_email }}
Password: {{ admin_password }}
IMPORTANT: Change password after first login!
- name: Configure Healthchecks integrations
hosts: healthchecks
become: true
tasks:
- name: Update Healthchecks configuration for integrations
copy:
dest: "{{ healthchecks_config_dir }}/env.conf"
owner: root
group: root
mode: '0640'
content: |
# Healthchecks Configuration
DB=sqlite:/data/hc.sqlite
SECRET_KEY={{ healthchecks_secret_key }}
SITE_ROOT=http://{{ healthchecks_domain }}:{{ healthchecks_port }}
SITE_NAME=Healthchecks
# Email settings
EMAIL_HOST={{ healthchecks_email_host }}
EMAIL_PORT={{ healthchecks_email_port }}
EMAIL_HOST_USER={{ healthchecks_email_user }}
EMAIL_HOST_PASSWORD={{ healthchecks_email_password }}
EMAIL_USE_TLS=True
DEFAULT_FROM_EMAIL={{ healthchecks_email_user }}
ALLOWED_HOSTS=*
# Slack integration
SLACK_CLIENT_ID=your_slack_client_id
SLACK_CLIENT_SECRET=your_slack_client_secret
# Discord integration
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
# Telegram integration
TELEGRAM_BOT_NAME=your_bot_name
TELEGRAM_TOKEN=your_telegram_token
# Pushover integration
PUSHOVER_API_TOKEN=your_pushover_token
PUSHOVER_SUBSCRIPTION_URL=http://your-server/subscribe/
# Matrix integration
MATRIX_USER_ID=@healthchecks:matrix.org
MATRIX_ACCESS_TOKEN=your_matrix_token
MATRIX_SERVER_NAME=matrix.org
- name: Restart Healthchecks container
community.docker.docker_compose:
project_src: "{{ healthchecks_data_dir }}"
state: present
restarted: true
- name: Backup Healthchecks data
hosts: healthchecks
become: true
vars:
healthchecks_data_dir: "/opt/healthchecks/data"
backup_dir: "/backup/healthchecks"
tasks:
- name: Create backup directory
file:
path: "{{ backup_dir }}"
state: directory
mode: '0755'
- name: Backup SQLite database
copy:
src: "{{ healthchecks_data_dir }}/hc.sqlite"
dest: "{{ backup_dir }}/hc-backup-{{ ansible_date_time.date }}.sqlite"
remote_src: true
- name: Backup configuration
archive:
path: "{{ healthchecks_config_dir }}"
dest: "{{ backup_dir }}/config-backup-{{ ansible_date_time.date }}.tar.gz"
- name: Clean up old backups (keep 7 days)
find:
paths: "{{ backup_dir }}"
patterns: "*.sqlite,*.tar.gz"
age: 7d
register: old_backups
- name: Remove old backups
file:
path: "{{ item.path }}"
state: absent
loop: "{{ old_backups.files }}"
Example of monitoring cron jobs with Healthchecks:
- name: Configure cron jobs with Healthchecks
hosts: monitored_hosts
become: true
vars:
healthchecks_url: "http://healthchecks-server:8000"
healthchecks_uuid: "your-check-uuid"
tasks:
- name: Create backup script with Healthchecks ping
copy:
dest: /usr/local/bin/backup-with-healthchecks.sh
owner: root
group: root
mode: '0755'
content: |
#!/bin/bash
UUID="{{ healthchecks_uuid }}"
HC_URL="{{ healthchecks_url }}/ping/$UUID"
# Start ping
curl -m 10 -fsS $HC_URL/start || true
# Run backup
if /usr/local/bin/backup.sh; then
curl -m 10 -fsS $HC_URL || true
else
curl -m 10 -fsS $HC_URL/fail || true
exit 1
fi
- name: Add cron job with Healthchecks
cron:
name: "Daily backup with Healthchecks"
minute: "0"
hour: "2"
job: "/usr/local/bin/backup-with-healthchecks.sh"
user: root
# Check container logs
docker logs healthchecks
# Check container status
docker ps -a | grep healthchecks
# Restart container
docker-compose -f /opt/healthchecks/data/docker-compose.yml restart
# Check database file
ls -la /opt/healthchecks/data/hc.sqlite
# Backup and recreate
docker-compose -f /opt/healthchecks/data/docker-compose.yml down
mv /opt/healthchecks/data/hc.sqlite /opt/healthchecks/data/hc.sqlite.bak
docker-compose -f /opt/healthchecks/data/docker-compose.yml up -d
# Test SMTP connection
docker exec healthchecks python manage.py sendtestemail admin@example.com
# Check email configuration
docker exec healthchecks cat /config/env.conf | grep EMAIL
# Reset admin password
docker exec healthchecks python manage.py changepassword admin@example.com
openssl rand -base64 32We develop tailored automation solutions for:
Let’s discuss your requirements: office@linux-server-admin.com | Contact