From 2a008d5e138e3a299b4bbf08c76226afdd5fdf99 Mon Sep 17 00:00:00 2001 From: Martijn Rondeel Date: Tue, 25 Sep 2018 12:00:37 +0200 Subject: [PATCH] Improve the readme and fix configuration issues --- README.md | 112 ++++++++++++++++++----------------------- config/config.json | 2 +- config/elastalert.yaml | 2 +- package.json | 2 +- 4 files changed, 53 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 38f32e80..fdc5366d 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ # Elastalert Server **A server that runs [ElastAlert](https://github.com/Yelp/elastalert) and exposes REST API's for manipulating rules and alerts. It works great in combination with our [ElastAlert Kibana plugin](https://github.com/bitsensor/elastalert-kibana-plugin).** -## Docker installation -The default configuration uses localhost as ES host. You will want to mount the volumes for configuration and rule files to keep them after container updates. In order to do that conviniently, please do a `git clone https://github.com/bitsensor/elastalert.git; cd elastalert` +## Installation +The most convenient way to run the ElastAlert server is by using our Docker container image. The default configuration uses `localhost:9200` as ElasticSearch host, if this is not the case in your setup please edit `es_host` and `es_port` in both the `config.yaml` and `config.json` configuration files. + +To run the Docker image you will want to mount the volumes for configuration and rule files to keep them after container updates. In order to do that conveniently, please do: `git clone https://github.com/bitsensor/elastalert.git; cd elastalert` -### Bash ```bash docker run -d -p 3030:3030 \ -v `pwd`/config/elastalert.yaml:/opt/elastalert/config.yaml \ @@ -15,77 +16,35 @@ docker run -d -p 3030:3030 \ --name elastalert bitsensor/elastalert:latest ``` -### Fish +## Building Docker image + +Clone the repository ```bash -docker run -d -p 3030:3030 \ - -v (pwd)/config/elastalert.yaml:/opt/elastalert/config.yaml \ - -v (pwd)/config/config.json:/opt/elastalert-server/config/config.json \ - -v (pwd)/rules:/opt/elastalert/rules \ - -v (pwd)/rule_templates:/opt/elastalert/rule_templates \ - --net="host" \ - --name elastalert bitsensor/elastalert:latest +git clone https://github.com/bitsensor/elastalert.git && cd elastalert ``` -### Configuration -#### ElastAlert parameters -ElastAlert supports additional arguments, that can be passed in the `config.json` file. An example is given in `config/config-historic-data-example.json`. - -## Installation using npm and manual ElastAlert setup - -### Requirements -- [ElastAlert v0.0.96](https://github.com/Yelp/elastalert/tree/v0.0.96). We don't support other versions of ElastAlert, use them at your own risk. -- [NodeJS 4.5.0](https://nodejs.org/en/download/) with NPM & NVM. - -## Building from source -1. Clone the repository - ```bash - git clone https://github.com/bitsensor/elastalert.git elastalert - cd elastalert - ``` -2. Run `nvm install "$(cat .nvmrc)"` to install & use the required NodeJS version. -3. Run `npm install` to install all the dependencies. -4. Look at the `Config` section to setup the path to your ElastAlert instance. - -Now, you can run the server with `npm start`. By default the server runs on http://localhost:3030. - -## Building -If you want to build the server and run the build version: - -1. Run the installation guide shown above -2. Run `npm run build` - -You can then start the build by running `node lib/index.js`. - +Build the image +``` +make build +``` +which is equivalent of +``` +docker pull alpine:latest && docker pull node:latest +docker build -t elastalert . +``` -## Building Docker image +### Options -1. Clone the repository - ```bash - git clone https://github.com/bitsensor/elastalert.git && cd elastalert - ``` -2. Build the image using - ``` - make build - ``` - which is equivalent of: - ``` - docker pull alpine:latest && docker pull node:latest - docker build -t elastalert . - ``` - -Custom Yelp's Elastalert version (a [release from github](https://github.com/Yelp/elastalert/releases)) e.g. `master` or `v0.1.28`: +Using a custom ElastAlert version (a [release from github](https://github.com/Yelp/elastalert/releases)) e.g. `master` or `v0.1.28` ```bash make build v=v0.1.28 ``` -Custom mirror: +Using a custom mirror ```bash docker build --build-arg ELASTALERT_URL=http://example.mirror.com/master.zip -t elastalert . ``` -### Install ElastAlert to /opt/elastalert -And run `pip install -r requirements.txt` or read the installation guide of ElastAlert. - -### Config +## Configuration In `config/config.example.json` you'll find the default config. You can make a `config.json` file in the same folder that overrides the default config. When forking this repository it is recommended to remove `config.json` from the `.gitignore` file. For local testing purposes you can then use a `config.dev.json` file which overrides `config.json`. You can use the following config options: @@ -117,6 +76,35 @@ You can use the following config options: "writeback_index": "elastalert_status" // Writeback index to examine for /metadata endpoint } ``` + +ElastAlert also expects a `config.yaml` with at least the following options. +```yaml +# The elasticsearch hostname for metadata writeback +# Note that every rule can have its own elasticsearch host +es_host: localhost + +# The elasticsearch port +es_port: 9200 + +# The index on es_host which is used for metadata storage +# This can be a unmapped index, but it is recommended that you run +# elastalert-create-index to set a mapping +writeback_index: elastalert_status + +# This is the folder that contains the rule yaml files +# Any .yaml file will be loaded as a rule +rules_folder: rules + +# How often ElastAlert will query elasticsearch +# The unit can be anything from weeks to seconds +run_every: + seconds: 5 + +# ElastAlert will buffer results from the most recent +# period of time, in case some log sources are not in real time +buffer_time: + minutes: 1 +``` ## API This server exposes the following REST API's: diff --git a/config/config.json b/config/config.json index 65dfe601..d3afcf46 100644 --- a/config/config.json +++ b/config/config.json @@ -13,7 +13,7 @@ "relative": true, "path": "/rule_templates" }, - "es_host": "elastalert", + "es_host": "localhost", "es_port": 9200, "writeback_index": "elastalert_status" } diff --git a/config/elastalert.yaml b/config/elastalert.yaml index 12306f99..2e251729 100644 --- a/config/elastalert.yaml +++ b/config/elastalert.yaml @@ -1,6 +1,6 @@ # The elasticsearch hostname for metadata writeback # Note that every rule can have its own elasticsearch host -es_host: elasticsearch +es_host: localhost # The elasticsearch port es_port: 9200 diff --git a/package.json b/package.json index 5f7cb001..7f26ee66 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@bitsensor/elastalert", - "version": "0.0.13", + "version": "0.0.14", "description": "A server that runs ElastAlert and exposes REST API's for manipulating rules and alerts.", "license": "MIT", "main": "index.js",