Pong

A minimal availability monitoring system with email alerts and push notifications.

Requirements

Pong is a dockerized Rails application run via docker-compose, so both a host running docker and a client with compose are required.

Configuration

Notifications

EMail

By default Pong uses mailgun as delivery method for ActionMailer. There's no specific reason other than easy integration via mailgun-ruby, and because they have a free plan with more than enough monthly sends for the purpose of occasional email alerts.

Since the free plan doesn't allow ad-hoc delivery, it's necessary to add the alert receiver as an Authorized Recipient in the mailgun account settings.

The application expects the following environment variables, either added in the default compose file, or added in the .env file.

MAILGUN_API_KEY
MAILGUN_DOMAIN
EMAIL_SENDER
EMAIL_RECEIVER

The sender is set as as default from address for all alerts, and the receiver is the target address for all alert mailings.

For now Pong only supports a single global receiver.

Push (via Telegram)

Pong supports push notifications, via direct chat messages over Telegram. This requires creating a dedicated Telegram bot and corresponding API key.

Here's the necessary steps:


1. Open the application, search for botfather and start a chat.
2. Create a new bot by issuing the `/newbot` command.
3. Go through the naming steps. Any name will do, but you'll need it shortly, so make it something you can remember. Once done, you'll be given a token to access the HTTP API. 4. Copy the API key into the the `.env` file for Pong. 5. We need the id, of the chat we're going to use for notifications. Pong includes a rake task, that runs the bot and replies with the id when a chat is started. Run this before the next step: $ docker-compose run web bin/rake telegram:run
6. Next open a chat with the newly created bot. Here you need the name you chose in step 3.
7. Upon joining the chat with the bot, you will be given the chat id we need. 8. Copy the chat id into the `.env` file, as you did with the api key and you're all set. Now Pong will send you notifications via this chat.

Docker image

For easier deployment, Pong is packaged as a fully self-contained docker image in production mode. A default image build is available on the dockerhub, but a custom or self built image can be used by setting the corresponding environment variable:

PROD_IMAGE=rhardih/pong:latest

Run

Bring up all compose services with:

docker-compose up -d

Database creation & initialization

docker-compose run web bin/rake db:create
docker-compose run web bin/rake db:migrate

How to run the test suite

This app uses the default minitest framework.

In development mode, a test compose service with a spring preloaded environment is added for running tests faster.

To run all tests:

docker-compose exec test bin/rake test

To run specific test:

docker-compose exec test bin/rake test TEST=test/jobs/request_job_test.rb

Services

The default application stack, as can also be seen in docker-compose.yml, consists of the following components:

Database server running PostgreSQL.
Key value store running redis.
A worker instance, running a resque worker.
A static job scheduler running resque-scheduler.
Default Puma web server.

Development

Aside from the services listed above, these are added for local development:

A test instance, with a preloaded spring environment.
A MailCatcher instance.

Deployment instructions

Assuming the production host is reachable and running docker, setting the following should be enough to let compose do deploys:

DOCKER_HOST=tcp://<url-or-ip-of-remote-host>:2376
DOCKER_TLS_VERIFY=1

Then adding reference to the production config:

docker-compose -f docker-compose.yml -f production.yml up -d

Remember to create and initialize the database as well.

System design notes

Check

In order to somewhat alleviate spurious alert triggerings, when a request for a check fails, it is put into an intermediate state of limbo. If a set number of subsequent request attempts are still failing, the check will then be marked as being down

Below is transition diagram illustrating how the status of a Check changes:

One thing to note, is that when a check is either in limbo or is down, its interval is disregarded, and a request is triggered every time the queue job is running, which is roughly once every minute.