# Quickstart

Creating a new check involves the following steps:

  1. Create a free Checkson account
  2. Implement your check logic
  3. Put it into a Docker image image, publish the image.
  4. Configure your check and notification channel

Let's look at an example. Imaging that you have rebranded your product and have switched to a new domain. You have set up a redirect from your old domain to the new one so that all visitors that have your old site bookmarked get sent to your new website. This is obviously very important so you want to monitor this redirect and make sure that the redirect itself works correctly and that the TLS certificate is not expired, etc.

# Create a free Checkson account

Go to https://app.checkson.io and login in with your Google or GitHub account. A Checkson account will be created for you.

# Implement check logic

In Python, this check could look like this:

import requests
import sys

EXPECTED_TARGET_URL = 'https://shinynewdomain.com'

response = requests.get('https://olddomain.com', allow_redirects=False)

if response.status_code != 301:
    print('Not redirected')

target_url = response.headers['Location']
if target_url != EXPECTED_TARGET_URL:
    print(f'Incorrect redirect location: {target_url}')

print('Redirected successfully')

If the redirect worked, an exit code of 0 is returned. Otherwise, an exit code of 1 is used instead. This let's Checkson know if the check was successful or not. You can test locally if this works:

python3 main.py

You can check the exit code of the last command like this:

echo $?

# Build and push Docker image

Let's now bundle this up in a Docker image and push it to a Docker registry, e.g. to Docker Hub.

This is the Dockerfile:

FROM python:3.10-slim

COPY . /app
RUN pip install -r requirements.txt

ENTRYPOINT ["python", "app.py"]

The next step is to build the image:

docker build . -t mydockerhubuser/checkson-redirect:1.0.0

Let's test it one last time locally:

docker run --rm -ti mydockerhubuser/checkson-redirect:1.0.0

And ship it off to Docker Hub:

docker push mydockerhubuser/checkson-redirect:1.0.0

# Configure check on Checkson

We can now configure the check using either the web application or using the Checkson CLI.

# Configuring the check with the CLI

Let's first see how to do it via the command line. Once you have installed it (instructions), you can setup the check as follows:

checkson create redirect-check \
  --docker-image mydockerhubuser/checkson-redirect:1.0.0 \
  --email stefan@huditech.com \
  --failure-threshold 2

What exactly did we do here? We are creating a check called redirect-check. We are configuring the Docker image to use with the --docker-image flag. We are also implicitely configuring a notification channel of type Email and associating it with the check, so that when it fails we are notified. The parameter --failure-treshold indicates that there must be two consecutive runs of the check with an exit code != 0 for the check to be considered unsuccessful and notifications to be sent out. Using a failure threshold can help to reduce the amount of false positives.

# Configuring the check with the web app

Let's first setup the notification channel. Go to Notification Channel and click on Create new notification channel.

Then enter select Email and enter your email address. Give the notification channel a name.

We are now ready to configure the check. Go to Checks and click Create new check.

Give the check a name, and configure the execution interval and the failure threshold.

We also have to enter the Docker image. We will obviously use the same image that we pushed earlier: mydockerhubuser/checkson-redirect:1.0.0.

Now we select the notification channel we created earlier. And finally click Create to finish the configuration of the check.

The check is now in place.

# Wrapping up

You now know how to create a check. Next, we will look at samples of checks which will give you more insights into topic we did not cover in this quickstart, like environment variables.