Is It Down Alert - Webpage Status Email Alerts

Note: for complex webpage status monitoring needs I would recommend checking out uptime-kuma. Uptime-kuma is an open-source self-hosted monitoring tool.

Validates if webpages are online on a predefined interval. Sends email alerts from gmail account if a page is down. Validation results are stored in a PostgresDB and displayed on a Dashboard built with Flask, Jinja and Chart.js. Quick and simple deployment using Docker containers.

Live example of Dashboard here.

Table of Contents

• Is It Down Alert - Webpage Status Email Alerts
  • Table of Contents
  • Features
  • Project Components
  • Requirements
  • Installation and Setup
    • Setting up a Gmail account to use as Sender
    • Setting up the project
    • Removing Docker container
  • Email Alert Example
  • PostgreSQL Database
  • Dashboard Webapp
    • Dashboard
    • Latest Request
  • Dependencies

Features

• Sends request to website periodically;
• Current time intervals allowed:
  • every x minutes;
  • every x hours;
  • every x days;
• Abstracts crontab job creation.
• User chooses which websites to check as well as the interval for each one by populating webpages.yaml
• If an http request does not return an expected response status code, an email is sent to a specified email address.
• Validation results stored in Postgres database.
• Dashboard website queries database and provides stats and charts to make information available to users.
• Fast deployment on any system with docker.

Project Components

User created webpages.yaml is read by Cronjobs container and for each of the webpages specified a cronjob is created. On each cronjob execution a history entry is created on a Postgres database table and if webpage was unreachable an email alert is sent. Adminer is a lightweight open source database management tool that may prove useful to easy run queries on database or perform admin operations.

To display and share status of checks performed on website a dashboard website was created. This webapp queries the database and displays the data on an easy to understand format.

Requirements

• Docker
• Docker Compose

Installation and Setup

Setting up a Gmail account to use as Sender

Important: Due to security reasons, create a new Gmail account to use as sender. Avoid using this account for other purposes.

After creating a Gmail account, an App Password needs to be created.

1. 2-Step Verification must be enabled on Google account settings > Security

2. Create an App Password:

On Select app choose Other (Custom name) and choose any name. Save the password for later use in project parameters.

Setting up the project

1. Clone the repository:

$ git clone https://github.com/tngaspar/isitdown-alert.git

2. Create .env file in project root folder with the following parameters:

SENDER_EMAIL=<Sender Gmail created = example@gmail.com>
APP_PASSWORD=<App Password created for Gmail Account>
RECEIVER_EMAIL=<Email that Receives Alerts = example@something.com>
TIME_ZONE=<Timezone for Email Timestamps. Example: Europe/Amsterdam>

HOST=db
POSTGRESUSER=<username to access postgres db>
POSTGRESPASSWORD=<password to access postgres db>
DATABASE=<database name>

Find a list of available time zones here.

3. Edit webpages.yaml and add all the webpages to check as well as the corresponding time intervals. This file already contains 2 examples and instructions on how to configure it.

4. Build and run the container:

$ docker-compose build  # Builds the container
$ docker-compose up -d  # Runs the container

Check if the container is running with the command docker ps.

That's it. The email alerts should now be activated.

Before deploying the final webpage list, I would recommend using an unreachable URL with a small interval to check if emails are being sent.

In a future release, I intend to add a way to track successfull requests to verify that all is up and running and keep a history of websites' downtimes.

Removing Docker container

$ docker-compose stop  # Stops the container
$ docker-compose rm  # Removes the container

Email Alert Example

Emails sent when website is unreachable have the following format:

PostgreSQL Database

Currently the database named cron has the following tables:

cron.dim_webpages:

Column	Type
id	integer Auto Increment [nextval('dim_webpages_id_seq')]
tag	character varying(2000) NULL
url	character varying(2000) NULL
interval	character varying(255) NULL

Stores webpages for which cronjobs were created and are currently active. This table mirrors the user input data from webpages.yaml.

cron.history:

Column	Type
id	integer Auto Increment [nextval('history_id_seq')]
request_time	timestamptz
tag	character varying(2000) NULL
url	character varying(2000)
is_up	boolean
status_code	integer NULL
response_url	character varying(2000) NULL

Stores results from validations over time. Creates a new record each time a cron job runs and a http request is made.

Dashboard Webapp

Dashboard that displays data from PostgreSQL database in an accessible format.

Flask used for routing. Jinja Corona Dark template used as base template for UI components. Chart.js used for dashboarding.

The webapp at the moment contains two pages:

Dashboard

High level stats, last 7 day chart and all request chart.

Currently active validations, time between requests and amount of requests previously made.

Latest Request

Table of latest request results. Shows the most recent 100 requests ordered from newest to oldest.

Dependencies

• Yagmail
• python-crontab
• PyYAML
• pytz
• python-dotenv
• psycopg2-binary
• Flask
• gunicorn

These dependencies may be found in the requirements.txt file and are installed while building docker containers.

For local development and debugging this dependencies are installed using:

$ pip install -r requirements.txt

During development I installed these in a virtualenv. More on python virtual environments here.

(back to top)