Using Docker to deploy Alerta

In this tutorial, you will learn how to deploy Alerta using Docker.

Contents

Overview

Prerequisites

Step 1: Run the container

Step 2: Customise configuration

Step 3: Run using docker-compose

Step 4: Install additional plugins or webhooks

Step 5: Complex setups

Production deployments

`Debugging and Troubleshooting`_

Overview

The “official” Docker image for Alerta has been download more than 2 million times and contains everything needed to deploy Alerta in most scenarios, such as:

Alerta API

Alerta Web UI

housekeeping

built-in and contributed plugins

built-in webhooks

all auth providers “ready-to-go”

More complex deployments can either use it as a base image and extend it with additional plugins, webhooks or alternatively, the Dockerfile can be used as a starting point to build your own base image.

Prerequisites

To follow this tutorial you will need access to a Docker environment where you can build Docker images and run containers. The fastest way to get going is to use Docker Desktop.

Follow the instructions on the Docker website and then return to this tutorial and continue with Step 1.

Note

If at any point in this tutorial something doesn’t work as expected remember that you can set DEBUG=1 for more verbose logging which you can access using the docker logs command. And you can always run a shell inside the container using docker exec -ti <container> sh command. All important configuration files are in the /app and /web directories.

Step 1: Run the container

We will first start a Postgres database container which is required by Alerta:

$ export POSTGRES_USER=alerta
$ export POSTGRES_PASSWORD=al3rt8

$ docker run --name alerta-db \
  -e POSTGRES_USER=$POSTGRES_USER \
  -e POSTGRES_PASSWORD=$POSTGRES_PASSWORD \
  -d postgres

Next, we start the Alerta docker container:

$ export DATABASE_URL=postgres://$POSTGRES_USER:$POSTGRES_PASSWORD@db:5432/alerta
$ docker run --name alerta-web \
  -e DATABASE_URL=$DATABASE_URL \
  --link alerta-db:db -d -p 8080:8080 alerta/alerta-web

Now get the container id of the Alerta server and tail the logs:

$ docker ps
CONTAINER ID        IMAGE               COMMAND                  CREATED              STATUS              PORTS                    NAMES
523906cd28e5        alerta/alerta-web   "docker-entrypoint.s…"   21 seconds ago       Up 21 seconds       0.0.0.0:8080->8080/tcp   alerta-web
ddd2a1333b38        postgres            "docker-entrypoint.s…"   About a minute ago   Up About a minute   5432/tcp                 alerta-db

$ docker logs -f 523906cd28e5  # note that your container id will be different

If it is running you should see log entries for the API server similar to the following:

2020-06-06 19:21:12,507 DEBG 'nginx' stdout output:
ip=\- [\06/Jun/2020:19:21:12 +0000] "\GET /api/config HTTP/1.1" \200 \873 "\-" "\python-requests/2.21.0"
/web | /api/config | > GET /api/config HTTP/1.1

Next try the API endpoint. Using curl the output would look like the following:

$ curl http://localhost:8080/api/alerts\?api-key\=5226852b-207c-47a6-9c7c-fce4d849347d
{
  "alerts": [],
  "autoRefresh": true,
  "lastTime": "2020-06-07T12:35:26.085Z",
  "message": "not found",
  "more": false,
  "page": 1,
  "pageSize": 1000,
  "pages": 0,
  "severityCounts": {},
  "status": "ok",
  "statusCounts": {},
  "total": 0
}

Generate an alert that you can then view in the Alerta web UI by running:

$ docker exec -ti 523906cd28e5 \
  alerta send \
  -E Development \
  -S Web \
  -r web01 \
  -e http5xx \
  -s warning \
  -t 'Too many 5xx responses'

Tip

Keep a copy of the returned alert id. You will need this in Step 4.

And finally, try browsing to the web UI using http://localhost:8080/

Step 2: Customise configuration

In Step 1 you launched an Alerta container using the default configuration.

To customise your Alerta server for your environment you can override the defaults using either environment variables (for common settings) or by mounting a configuration file into the container.

Configuration via Environment variables

A full list of environment variables supported by the Alerta docker image can be found in the README file. They include all of the most common settings for a standard deployment.

You already used one environment variable (DATABASE_URL) to tell Alerta where the database could be found and what the database credentials were.

The environment variables ADMIN_PASSWORD, ADMIN_KEY, ADMIN_KEY_MAXAGE, and HEARTBEAT_SEVERITY are only supported by the Docker container and are provided specifically to ease the deployment of Alerta in Docker environments.

Of these, it is really only ADMIN_PASSWORD that needs to be set otherwise the default password of “alerta” will be assigned.

It can be useful to also set ADMIN_KEY to a known value otherwise an random API key will be generated with admin privileges. That API key can be assigned by a configuration management tool and used when integrating with other tools, for example.

So, to run Alerta with set values for ADMIN_PASSWORD and ADMIN_KEY, and to enable DEBUG run:

$ docker run --name alerta-web \
  -e DATABASE_URL=$DATABASE_URL \
  -e DEBUG=1 \
  -e ADMIN_PASSWORD=Pa55w0rd \
  -e ADMIN_KEY=docker-api-key \
  --link alerta-db:db -d -p 8080:8080 alerta/alerta-web

Note

Use the above command for this tutorial but remember to set your ADMIN_PASSWORD and ADMIN_KEY to something different when deploying to your environment.

The default admin username is “alerta”. This can be set using ADMIN_USERS which allows you to set one or more admin users to be created at container launch time:

$ docker run --name alerta-web \
  -e DATABASE_URL=$DATABASE_URL \
  -e ADMIN_USERS=alice,bob,charlotte,dave \
  -e ADMIN_PASSWORD=Pa55w0rd \
  -e ADMIN_KEY=docker-api-key \
  --link alerta-db:db -d -p 8080:8080 alerta/alerta-web

One of the important benefits of the Docker image is that many plugins come pre-installed so the container starts immediately the database is available.

However, only a few plugins are enabled by default ie. remote_ip, reject, heartbeat, blackout, forwarder. To enable more, or to disable some of the defaults, use the PLUGINS environment variable like so:

$ docker run --name alerta-web \
  -e DATABASE_URL=$DATABASE_URL \
  -e ADMIN_USERS=alice,bob,charlotte,dave \
  -e ADMIN_PASSWORD=Pa55w0rd \
  -e ADMIN_KEY=docker-api-key \
  -e PLUGINS=reject,heartbeat,blackout,normalise \
  --link alerta-db:db -d -p 8080:8080 alerta/alerta-web

By now, you can see that the number of environment variables listed on the command line is growing and becoming unmanageable and we haven’t even looked at all the different authentication settings.

Configuration via external `alertad.conf` file

So now we will use a configuration file that we can mount into the container at run time. The alternative is to continue using environment variables (if we only need to set configuration that is supported by environment variables) but instead of using docker run we use docker-compose and its YAML configuration file.

We look at using docker-compose next, however, for now let’s see how we can set any configuration setting using an external alertad.conf file.

Create a file called alertad.conf in your current working directory and we will include all of the environment variable settings from above and a few more, so you can see how they compare:

DEBUG=True
DATABASE_URL='postgres://alerta:al3rt8@db:5432/alerta'
AUTH_REQUIRED=True
ADMIN_USERS=['alice','bob','charlotte','dave']
ADMIN_PASSWORD='Pa55w0rd'
ADMIN_KEY='docker-api-key'
PLUGINS=['reject','heartbeat','blackout','normalise']

The most important difference to note is that the configuration file must be valid Python, so strings must be quoted, comma-separated variables become Python lists, 1 becomes True etc.

Then to mount this file into the docker container at run time use:

$ docker run --name alerta-web \
  -v $PWD/alertad.conf:/app/alertad.conf \
  --link alerta-db:db -d -p 8080:8080 alerta/alerta-web

Note

You may first need to stop your previous Alerta container.

You should see that if you log out of the web UI you will be forced to login if you want to continue. This proves that the AUTH_REQUIRED setting was read from the supplied configuration file. Excellent!

However, things are starting to get a little more complex now as we have an additional file to manage as well as remembering the exact command to launch Postgres and the Alerta API. And stopping and starting the containers at the right time and in the right order becomes tricky if we add more dependencies to your monitoring stack, like Prometheus and Alertmanager, for example.

This is where container orchestration comes into play. And the first step towards Docker container configuration and deployment is to use the docker-compose tool which we will look at now.

Step 3: Run using docker-compose

The docker-compose tool can be used to launch an entire Docker container stack with one command, namely docker-compose up.

Create a new file called docker-compose.yaml in your current working directory and include the following:

version: '3'
services:
  api:
    image: alerta/alerta-web
    ports:
      - 8080:8080
    environment:
      - DEBUG=1
      - DATABASE_URL=postgres://alerta:8l3rt8@db:5432/alerta
      - AUTH_REQUIRED=True
      - ADMIN_USERS=alice,bob,charlotte,dave
      - ADMIN_PASSWORD=Pa55w0rd
      - ADMIN_KEY=docker-api-key
      - PLUGINS=reject,heartbeat,blackout,normalise
    networks:
      - net
    depends_on:
      - db
    restart: always
  db:
    image: postgres
    volumes:
      - ./pg-data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: alerta
      POSTGRES_USER: alerta
      POSTGRES_PASSWORD: 8l3rt8
    networks:
      - net
    restart: always
networks:
  net: {}

Now launch both Alerta and Postgres at the same time using:

$ docker-compose up

And verify by browsing to http://localhost:8080 as before.

You can replace environment: with volumes: if you want or need to mount a configuration file into the container, like so:

version: '3'
services:
  web:
    image: alerta/alerta-web
    ports:
      - 8080:8080
    volumes:
      - ./alertad.conf:/app/alertad.conf
    networks:
      - net
    depends_on:
      - db
    restart: always
  db:
    image: postgres
    volumes:
      - ./pg-data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: alerta
      POSTGRES_USER: alerta
      POSTGRES_PASSWORD: 8l3rt8
    networks:
      - net
    restart: always
networks:
  net: {}

Step 4: Install additional plugins or webhooks

Docker containers should be treated as “immutable” infrastructure which means that once deployed they should not be modified. So if you need to use a custom plugin or webhook not already pre-installed then you will need to install it during image build time, not after the container as been deployed.

To do this you can extend the base image by creating a Dockerfile and using the FROM instruction. For example, to install the MS Teams webhook create a Dockerfile as below:

FROM alerta/alerta-web

RUN /venv/bin/pip install \
    git+https://github.com/alerta/alerta-contrib.git#subdirectory=webhooks/msteams

You can either build the Docker image using the docker build command or add a reference to your docker-compose.yaml file and use docker-compose build. Modify the docker-compose.yaml as follows adding the build line and changing the image line slightly to remove the “alerta/” organisation reference like so:

version: '3'
services:
  web:
    build: .
    image: alerta-web
    ports:
      - 8080:8080
    volumes:
      - ./alertad.conf:/app/alertad.conf
    networks:
      - net
    depends_on:
      - db
    restart: always
  db:
    image: postgres
    volumes:
      - ./pg-data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: alerta
      POSTGRES_USER: alerta
      POSTGRES_PASSWORD: 8l3rt8
    networks:
      - net
    restart: always
networks:
  net: {}

Now build the new image and run it using:

$ docker-compose up --build

Once again you should be able to browse to http://localhost:8080 and log in to the web console.

To verify that the MS Teams webhook is now available, use curl to send a HTTP POST request to the webhook URL (replace alert_id with your alert id from Step 1):

$ curl -XPOST http://localhost:8080/api/webhooks/msteams \
-H 'Content-Type: application/json' \
-H 'X-API-Key: docker-api-key' \
-d '{"action":"ack","alert_id":"da9b3d24-3ee3-4cdc-8a58-a6533c9e9af9"}'
{
  "message": "status changed",
  "status": "ok"
}

Step 5: Complex setups

Alerta, just like any web service, can be deployed in numerous different ways to suit your environment. Most commonly, it will be deployed behind a reverse proxy (which would be responsible for SSL termination) and perhaps on a sub-path such as /alerta (eg. https://monitoring.example.com/alerta/ui)

It is beyond the scope of this introductory tutorial to step you through every possible scenario however, below is a list of example docker-compose deployments that illustrate some of these scenarios:

Apache reverse proxy

Envoy proxy

nginx reverse proxy

Traefik proxy

Production deployments

Despite what Docker say, it is not advisable to use docker-compose for production deployments. Instead you should consider container runtime platforms such as Kubernetes, AWS Elastic Container Service, or Google Cloud GKE.

Next Steps

In a future tutorial, you will learn how to deploy Alerta with Kubernetes using a tool called mini-kube. So stay tuned!

Using Docker to deploy Alerta

Overview

Prerequisites

Step 1: Run the container

Step 2: Customise configuration

Configuration via Environment variables

Configuration via external alertad.conf file

Step 3: Run using docker-compose

Step 4: Install additional plugins or webhooks

Step 5: Complex setups

Production deployments

Next Steps

Configuration via external `alertad.conf` file