Skip to content

Latest commit

 

History

History
166 lines (105 loc) · 7.19 KB

INSTALL.adoc

File metadata and controls

166 lines (105 loc) · 7.19 KB
Raw

Cerebro: open alerting for DevOps teams

Design

There is one supported backend for now: Graphite, the opensource timeseries database. Cerebro currently integrates with Seyren to store alarms, schedule checks and send alerts. Why not use vanilla Seyren? Because we thought an on-top interface would better meet our requirements for managing large sets of alarms in a collaborative manner, and making alerting over various types of metrics more accessible to Graphite non-experts.

We try to keep Cerebro as stateless as possible (over backends): no user profile, no ownership over alarms (this one is more a 'DevOps decision' than a 'stateless decision'), stateless authentication (we currently use JWT with Keycloak for auth).

Expect Cerebro to integrate with other backends in the future: Elasticsearch / ElastAlert, possibly Grafana 4 alerting feature, etc.

Code structure (Maven modules) :

  • dashboard : graphical user interface, running Angular 2 (TypeScript, Bootstrap, etc.)

  • docker : Docker / Compose implementation to run a Graphite+Mongo+Seyren+Cerebro stack of containers

  • selenium : Selenium integration tests over dashboard features

  • services : REST API over backends, running Spring / Java

Dependencies

Runtime dependencies (see the Run section):

  • Running Graphite and Seyren instances (we currently use Graphite 0.9.14 and Seyren 1.5.0)

  • Java 8 to run the Cerebro Services JAR

  • A Web server (we use Apache 2) to run the Cerebro Dashboard

  • SMTP service to send email notifications

Static dependencies (libs and devtools) can be listed from build descriptors, namely the pom.xml files (incl. Spring, Jackson, Selenium, etc.) and package.json (incl. Angular 2, TypeScript, Bootstrap, Introjs, etc.).

Build from sources

Prerequisites:

To build Cerebro from sources, from project root folder:

$ mvn clean verify

Once built, the services and dashboard archives are available in target subfolders.

Run with Docker

TL;DR

Easily run and play with Cerebro with the provided Docker / Compose implementation:

$ mvn clean verify
$ cd docker
$ docker-compose up

Links:

Note
 Local IP may be different for Docker Toolbox users.

You may want to check the sources in the docker module: Dockerfile, default properties, backends versions, etc.

Compose details

The docker-compose up command builds the src image (which contains sources and config files) then runs lots of things:

Run with Maven / NPM (dev)

For development and local tests, we often use spring-boot:run or standard java -jar, plus NPM to run the dashboard (Graphite and Seyren services must be running).

Services layer:

$ cd services
$ mvn spring-boot:run

Dashboard:

$ cd dashboard
$ npm install
$ npm start

Links:

Run with Java / Apache (standard)

For standard deployment run scenarios (meaning without Docker, Maven or NPM), we use standard java -jar (services) and Apache HTTPd (dashboard).

Services layer:

$ cd services
$ java -jar target/cerebro-services-1.0.0-SNAPSHOT.jar
Note
 that is not what we do (make JAR not WAR), but some might prefer to build a WAR then deploy it to <insert_best_java_server_available>.

Dashboard:

To run the dashboard (Angular 2 with routing) with Apache 2, extract the TAR.GZ file to HTTPd and check the .htaccess instructions:

RewriteEngine On
# If an existing asset or directory is requested go to it as it is
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR]
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d
RewriteRule ^ - [L]
# If the requested resource doesn't exist, use index.html
RewriteRule ^ /index.html
Note
 Any static resource Web server should do the job.

Configuration

Service layer

Location: services/src/main/resources/config.

Main properties are:

  • From email.properties:

    • server - The SMTP service host

    • port - The SMTP service port

    • sender - The notification 'from' email

  • From instance.properties:

    • seyren.host - The Seyren backend instance

    • graphite.sources[0].url - The Graphite backend instance

Dashboard

Location: dashboard/config.

Main properties are:

  • From globals.json:

    • services_url - The Cerebro service layer URL

    • theme.headerImage - The Cerebro top-background image URL

    • theme.logo - The Cerebro loading-logo image URL

    • contacts.xxxxxx - Insert your own wiki, email, issue tracker, etc. here, for users to get these links in the Learn more…​ page

      IMPORTANT

      the Cerebro default logo/background images are links to external images from the X-Men licence/movies. Those images are not part of Cerebro sources, only their URL is embedded, merely illustrating a possible look’n’feel for the application. Please replace them with other resources of your own and customize the logo/background for your needs.

Authentication?

Even if authentication config is commented out by default, we use Cerebro with Keycloak and stateless JWT tokens. Search keycloak in services and dashboard sources to known more (possibly testing it yourself). We should provide more explanations and auth code in the future.