WSGI Server

There are many ways to deploy Alerta. It can be run as alertad during development or testing but when run in a production environment, it should always be deployed as a WSGI application. See the list of real world examples below for different ways to run Alerta as a WSGI application.

When deploying with Apache mod_wsgi, be aware that by default Apache strips the Authentication header. This will cause you to receive “Missing authorization API Key or Bearer Token” errors. This can be fixed by setting WSGIPassAuthorization On in the configuration file for the site.

Web Proxy

Running the Alerta API behind a web proxy can greatly simplify the Web UI setup which means you can completely avoid the potential for any cross-origin issues.

Also, if you run the API on an HTTPS/SSL endpoint then it can reduce the possibility of mixed content errors when a web application hosted on a HTTP endpoint tries to access resources on an HTTPS endpoint.

Example API configuration (extract)

This example nginx server is configured to serve the web UI from the root / path and reverse-proxy API requests to /api to the WSGI application running on port 8080:

server {

        listen 80 default_server deferred;

        access_log /dev/stdout main;

        location /api/ {
                proxy_pass http://backend/;
                proxy_set_header Host $host:$server_port;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        location / {
                root /app;

upstream backend {
        server localhost:8080 fail_timeout=0;

The web UI configuration file config.js for this setup would simply be /api for the endpoint value, as follows:

'use strict';

angular.module('config', [])
  .constant('config', {
    'endpoint'    : "/api",
    'provider'    : "basic"

Static Website

The Alerta web UI is just a directory of static assets that can be served from any location. An easy and cheap way to serve the web UI is from an Amazon S3 bucket as a static website.


Serving the Alerta web UI from a static web hosting site will not work unless that domain is listed in the CORS_ORIGINS Alerta API server configuration settings.

Authentication & SSL

Alerta supports several authentication mechanisms for both the API and the web UI and some key features of the web UI, like watching alerts, are only available if authentication is enabled.

The API can be secured using API Keys and the web UI can be secured using Basic Auth or an OAuth provider from either Google or Github.

If you plan to make the web UI accessible from a public URL it is strongly advised to enforce authentication and use HTTPS/SSL connections to the Alerta API to protect private alert data.

Authorisation & Customer Views

To restrict access to certain features use roles and customer views.


Alerta can scale horizontally, in the same way any other web application scales horizontally – a load balancer handles the HTTP requests and distributes those requests between all available application servers.


If using multiple API servers ensure the same SECRET_KEY is used across all servers otherwise there will be problems with web UI user logins.

High Availability

To achieve high system availability the Alerta API should be deployed to scale out horizontally and the MongoDB database should be deployed as a replica set.

House Keeping

There are some jobs that should be run periodically to keep the Alerta console clutter free. To timeout expired alerts and delete old closed alerts you need to trigger housekeeping.

This can be done with the alerta command-line tool:

$ alerta housekeeping

This was not supported by earlier versions of the command-line tool and cURL has to be used to access /management/housekeeping.

The API key needs an admin scope if AUTH_REQUIRED is set to True.

It is suggested that you run housekeeping at regular intervals via cron. Every minute is a suitable interval.

By default, when you run housekeeping, Alerta will remove any alerts that have been expired or closed for 2 hours and any info messages that are 12 hours old. In some cases, these retention periods may be too long or too short for your needs. Bear in mind that Alerta is intended to reflect the here and now, so long deletion thresholds should be avoided. Where you do need to depart from the defaults, you can specify like this:

$ alerta housekeeping –expired 2 –info 12

In earlier versions of Alerta, a script called housekeepingAlerts.js was used for housekeeping. This is now deprecated.

Heartbeats can be sent from any source to ensure that a system is ‘alive’. To generate alerts for stale heartbeats the alerta command-line tool can be used:

$ alerta heartbeats --alert

Again, this should be run at regular intervals via cron or some other scheduler.

Management & Metrics

Use the management endpoint /management/status to keep track of realtime statistics on the performance of the Alerta API like alert counts and average processing time. For convenience, these statistics can be viewed in the About page of the Alerta web UI or using the alerta command-line tool status command.

Web UI Analytics

Google analytics can be used to track usage of the Alerta web UI console. Just create a new tracking code with the Google analytics console and add it to the config.js web console configuration file:

'use strict';

angular.module('config', [])
  .constant('config', {
    'endpoint'    : "/api",
    'provider'    : "basic",
    'tracking_id' : "UA-NNNNNN-N"  // Google Analytics tracking ID

Real World Examples

Below are several different examples of how to run Alerta in production from a Debian vagrant box, an AWS EC2 instance, RedHat Openshift PaaS to a Docker container.

  • Vagrant - deploy Alerta stand-alone or with Nagios, Zabbix, Riemann, Sensu or Kibana
  • Heroku - deploy the Alerta API and the web ui to Heroku PaaS
  • OpenShift - deploy the Alerta API to OpenShift Paas
  • AWS EC2 - deploy Alerta to EC2 using AWS Cloudformation
  • Docker - deploy Alerta to a docker container
  • Packer - deploy Alerta to EC2 using Amazon AMIs
  • Flask deploy - deploy Alerta as a generic Flask app
  • Ansible - deploy Alerta using ansible on Centos 7