How to setup a self hosted status page to monitor your websites with a single-board computer • Linux Boards

Whether you have a personal blog or a website for your main or side business, ensuring your websites are up and running smoothly is crucial. A self-hosted status page helps you monitor the uptime and performance of your sites.

This guide will show you how to set up a self-hosted status page using the Gatus project on a single-board computer (SBC) like a Raspberry Pi, leveraging Docker Compose for an easy setup. We’ll also cover configuring email and Telegram alerts for instant notifications.

Though the process is very simple, if you struggle in some parts of this guide, all the code seen in this guide will be hosted on the following GitHub repository so you can try it yourself.

LinuxBoards/status-page-project

Why use a status page?

A status page provides a transparent way to communicate the status of your services. It helps in:

Monitoring website uptime and performance.
Alerting you instantly about any downtime.
Building trust with users by showing them real-time service status.

Configure status page

For this project we will be using Gatus.

Gatus is a developer-oriented health dashboard for monitoring services using HTTP, ICMP, TCP, and DNS queries. It evaluates results with conditions on status codes, response times, certificate expiration, and more. It also supports alerting through email, Telegram, Slack, Teams, PagerDuty, Discord, Twilio, and other platforms.

Prerequisites

Before we begin, ensure you have the following:

A single-board computer (e.g., Raspberry Pi) with a running Linux OS.
Docker and Docker Compose installed on your SBC.
Access to an email server and a Telegram account and bot token for alerts.

1. Install Docker and Docker Compose

First, let’s install Docker and Docker Compose on your SBC. Open a terminal and run the following commands:

# Update and upgrade package list
sudo apt update -y && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh

# Install Docker Compose
sudo apt install -y docker-compose

# Start the Docker service
sudo systemctl restart docker.service

Verify the installation:

docker --version
docker-compose --version

2. Create a local Git repository

Create a directory where we will be creating all files needed for the status page. Well will also track all changes of the project in a Git repository to better manage the changes.

# Create a project directory
mkdir -p status-page
cd status-page

# Initialize git repository
git init

# Create your main branch
git checkout -b main

If you decide to push this local repository to a remote public or private repository in GitHub, GitLab, Bitbucket or other hosted git repository service, you can push your changes with the following:

# Set your origin. Using SSH URL pointed to GitHub
git remote add origin [email protected]:<USERNAME>/<REPOSITORY>.git

Where <USERNAME> is your GitHub username and <REPOSITORY> the repository you created for this project.

3. Create a Docker Compose file

Create a docker-compose.yml file in the directory with the following content:

services:
  gatus:
    image: twinproduction/gatus:latest
    restart: unless-stopped
    ports:
      - 8080:8080
    env_file:
      - .env
    volumes:
      - ./config:/config
    networks:
      - backend
      - database
    depends_on:
      - postgresql

  postgresql:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: "${DB_NAME}"
      POSTGRES_USER: "${DB_USER}"
      POSTGRES_PASSWORD: "${DB_PASS}"
      POSTGRES_INITDB_ARGS: --auth-host=scram-sha-256 --auth-local=scram-sha-256
      POSTGRES_HOST_AUTH_METHOD: scram-sha-256
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U '${DB_USER}' -h '${DB_HOST}' -d '${DB_NAME}'"]
      interval: 1m
      timeout: 30s
      retries: 3
      start_period: 1m30s
    networks:
      - database
    volumes:
      - pgsqldata:/var/lib/postgresql/data

networks:
  backend: {}
  database: {}

volumes:
  pgsqldata: {}

3.1. Setting up environment variables

The following environment variables, from a file named .env, will be used to configure some parts of the application, including the logo and database conecction.

APP_TITLE='Status Page'
APP_DESCRIPTION='Status page for my personal websites'
APP_HEADER='My status page'
APP_LOGO='https://i.imgur.com/lYVCvAG.png'
APP_LINK='https://linuxboards.com'

DB_HOST=postgresql
DB_PORT=5432
DB_NAME=
DB_USER=
DB_PASS=
DATABASE_DSN="postgres://${DB_USER}:${DB_PASS}@${DB_HOST}:${DB_PORT}/${DB_NAME}?sslmode=disable"

DNS_RESOLVER=1.1.1.1

TELEGRAM_BOT_TOKEN=
TELEGRAM_USER_ID=

EMAIL_HOST=
EMAIL_PORT=587
EMAIL_FROM=
EMAIL_USERNAME=
EMAIL_PASSWORD=
EMAIL_INSECURE=false
EMAIL_TO=

4. Configure Gatus

Create a config.yaml file in a config directory. This file will define the services you want to monitor and the alerting mechanisms.

mkdir -p config && touch config/config.yaml

Here is an example configuration file:

ui:
  title: '${APP_TITLE}'
  description: '${APP_DESCRIPTION}'
  header: '${APP_HEADER}'
  logo: '${APP_LOGO}'
  link: '${APP_LINK}'

storage:
  type: postgres
  path: '${DATABASE_DSN}'

x-uptime-options: &uptime-options
  interval: 1m
  conditions:
    - '[STATUS] == 200'
    - '[RESPONSE_TIME] < 1000'
  alerts:
    - type: email
      description: 'Website uptime validation'
      send-on-resolved: true

x-domain-options: &domain-options
  client:
    dns-resolver: 'tcp://${DNS_RESOLVER}:53'
  interval: 5m
  conditions:
    - '[DOMAIN_EXPIRATION] > 720h'
  alerts:
    - type: email
      description: 'Website domain validation'
      send-on-resolved: true

x-cert-options: &cert-options
  client:
    dns-resolver: 'tcp://${DNS_RESOLVER}:53'
  interval: 5m
  conditions:
    - '[CERTIFICATE_EXPIRATION] > 48h'
  alerts:
    - type: email
      description: 'Website SSL/TLS certificate validation'
      send-on-resolved: true

alerting:
  email:
    host: '${EMAIL_HOST}'
    port: ${EMAIL_PORT}
    username: '${EMAIL_USERNAME}'
    password: '${EMAIL_PASSWORD}'
    from: '${EMAIL_FROM}'
    to: '${EMAIL_TO}'
    client:
      insecure: ${EMAIL_INSECURE}

  telegram:
    token: '${TELEGRAM_BOT_TOKEN}'
    id: '${TELEGRAM_USER_ID}'

endpoints:
  # Uptime
  - name: Linux Boards
    group: 01. Web
    url: 'https://linuxboards.com'
    <<: *uptime-options

  # Domain
  - name: Duck Duck Go
    group: 02. Domains
    url: 'https://duckduckgo.com'
    <<: *domain-options

  # Certificates
  - name: Example Domain
    group: 03. Certificates
    url: 'https://example.org'
    <<: *cert-options

4.2. Setting up email alerts

To send email alerts you’ll need to configure a SMTP server. You could use the one from any existing email service you use like Zoho Mail, or for testing you could use services like Mailtrap or Mailpit.

EMAIL_HOST=
EMAIL_PORT=587
EMAIL_FROM=
EMAIL_USERNAME=
EMAIL_PASSWORD=
EMAIL_INSECURE=false
EMAIL_TO=

Information like the host, port, from, username and password are given by the email service. The EMAIL_INSECURE environment variable controls wheter it should skip TLS validation. Most SMTP services support this so you can leave it as false (do not skip validation).

The EMAIL_TO is a string of comma separated email address where the notification will be sent to.

4.3. Setting up Telegram alerts

For Telegram alerts you’ll need to create a bot with @BotFather to get a bot token.

Then you’ll need your user ID so the notifications will be sent only to you. You can use some bots that give you this information like @MissRose_bot.

5. Start Gatus

Now the most exiting part of the guide: running our own status page.

sudo docker-compose up --remove-orphans --force-recreate -d

Gatus will now be running, and you can access the status page by visiting http://localhost:8080 in your web browser.

6. Verify your setup

Visit the status page to verify that your website is being monitored. You should see the service you defined and its current status. Test the alerting by temporarily taking your website offline and checking if you receive email and Telegram notifications.

You can also see the Docker Compose logs to check that everything is running correctly.

sudo docker-compose logs --tail 250 -f

Conclusion

Setting up a self-hosted status page to monitor your websites using a single-board computer is straightforward with Gatus and Docker Compose. This setup ensures you’re instantly alerted about any issues, allowing you to maintain high uptime and reliability for your users. Stay proactive and keep your services running smoothly!

For more detailed configurations and options, refer to the Gatus documentation.

Meet Gatus - An Advanced Uptime Health Dashboard

By following this guide, you ensure your websites are monitored effectively, leveraging the power of self-hosted solutions on single-board computers and modern alerting mechanisms. Happy monitoring!