Skip to content

Latest commit

 

History

History
257 lines (184 loc) · 8.58 KB

deployment.rst

File metadata and controls

257 lines (184 loc) · 8.58 KB

Deployment

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 :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.

Note

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 :ref:`watching alerts <watched alerts>`, are only available if authentication is enabled.

The API can be secured using :ref:`API keys` and the web UI can be secured using :ref:`Basic Auth <basic auth>` or an :ref:`OAuth <oauth2>` provider from either Google or Github.

If you plan to make the web UI accessible from a public URL it is strongly advised to :ref:`enforce authentication <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 :ref:`roles <user roles>` and :ref:`customer views <customer views>`.

Scalability

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.

Note

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 :ref:`horizontally <scalability>` 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.

:ref:`Heartbeats <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 :file:`/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 :ref:`status <cli_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