<commit_before>What is Alerta?
===============

The alerta monitoring system is a tool used to consolidate and
de-duplicate alerts from multiple sources for quick ‘at-a-glance’
visualisation. With just one system you can monitor alerts from
many other monitoring tools on a single screen.

How to use this image
=====================

To use this image run either a `mongo` or `postgres` container first:

    $ docker run --name alerta-db -d mongo

Then link to the database container when running the `alerta-web` container:

    $ export DATABASE_URL=mongodb://db:27017/monitoring
    $ docker run --name alerta-web -e DATABASE_URL=$DATABASE_URL --link alerta-db:db \
    -d -p <port>:8080 alerta/alerta-web

The API endpoint is at:

    http://<docker>:<port>/api

Browse to the alerta console at:

    http://<docker>:<port>/

Environment Variables
---------------------

The following environment variables are supported for configuring
the `alerta-web` container specifically for Docker deployments:

`ADMIN_PASSWORD`
    - sets the password of all admins. Should be changed at first login.

`ADMIN_KEY`
    - sets an admin API key.

`HEARTBEAT_SEVERITY`
    - severity used to create alerts for stale heartbeats

The following environment variables are supported by the Alerta
API to ease deployment more generally:

`DEBUG`
    - debug mode for increased logging. (eg. `DEBUG=1`)

`BASE_URL`
    - used to make links in API responses relative. (default: `/api`)

`SECRET_KEY`
    - a unique, randomly generated sequence of ASCII characters.

`DATABASE_URL`
    - database connection URI string. Only MongoDB and Postgres allowed.

`DATABASE_NAME`
    - used to override database name in `DATABASE_URL`.

`AUTH_REQUIRED`
    - require users to authenticate when using web UI or `alerta` CLI.

`ADMIN_USERS`
    - comma-separated list of logins that will be created with "admin" role.

`CUSTOMER_VIEWS`
    - enable alert views partitioned by customer. (default:``False``)

`OAUTH2_CLIENT_ID`
    - client ID required by OAuth2 provider

`OAUTH2_CLIENT_SECRET`
    - client secret required by OAuth2 provider

`ALLOWED_EMAIL_DOMAINS`
    - list of authorised email domains when using Google

`GITHUB_URL`
    - GitHub Enteprise URL for privately run GitHub server

`ALLOWED_GITHUB_ORGS`
    - list of authorised GitHub organisations when using GitHub

`GITLAB_URL`
    - GitLab website URL for public or privately run GitLab server

`ALLOWED_GITLAB_GROUPS`
    - list of authorised GitLab groups when using GitLab

`KEYCLOAK_URL`
    - Keycloak URL

`KEYCLOAK_REALM`
    - Keycloak realm

`ALLOWED_KEYCLOAK_ROLES`
    - Keycloak roles

`CORS_ORIGINS`
    - list of URL origins that can access the API

`MAIL_FROM`
    - valid email address from which verification emails are sent

`SMTP_PASSWORD`
    - password for ``MAIL_FROM`` email account

`PLUGINS`
    - list of plugins to enable.

Configuration Files
-------------------

To set configuration settings not supported by environment variables use
configuration files instead. For example:

    $ docker run -v $PWD/config/alertad.conf:/app/alertad.conf \
      -v $PWD/config/config.json:/web/config.json \
      -p <port>:8080 alerta/alerta-web

For a full list of server configuration options see https://docs.alerta.io.

Plugins
-------

All built-in and contributed plugins are installed at image build time. Only
plugins listed in `PLUGINS` environment variabled will be enabled.

In the example below, of all the plugins installed only those listed will
be enabled at container start time:

    PLUGINS=remote_ip,reject,heartbeat,blackout,slack,prometheus

Custom plugins should be installed as an additional image layer.

Authentication
--------------

To make it easy to get going with Alerta on docker quickly, the default image
will use Basic Auth for user logins and login will be optional.

To allow users to login using Google OAuth, go to the [Google Developer Console][1]
and create a new client ID for a web application. Then set the `CLIENT_ID`
and `CLIENT_SECRET` environment variables on the command line as follows:

    $ export CLIENT_ID=379647311730-6tfdcopl5fodke08el52nnoj3x8mpl3.apps.googleusercontent.com
    $ export CLIENT_SECRET=<KEY>

Now pass in the defined environment variables to the `docker run` command:

    $ docker run --name alerta-web  -e PROVIDER=google -e CLIENT_ID=$CLIENT_ID \
    -e CLIENT_SECRET=$CLIENT_SECRET -d -p <port>:8080 alerta/alerta-web

This will allow users to login but will only make it optional. To enforce
users to login you must also set the `AUTH_REQUIRED` environment variable to
`True` when starting the docker image:

    $ docker run --name alerta-web -e AUTH_REQUIRED=True -e ...

To restrict logins to a certain email domain set the `ALLOWED_EMAIL_DOMAIN`
environment variable as follows:

    $ docker run --name alerta-web -e ALLOWED_EMAIL_DOMAIN=example.com ...

GitHub and GitLab can also be used as the OAuth2 providers by setting the
`PROVIDER` environment variable to `github` and `gitlab` respectively. For
more information on using GitHub, GitHub Enterprise or GitLab as th OAuth2
provider see https://docs.alerta.io

Docker Compose
--------------

Use `docker-compose` to create and start Alerta and Postgres with
one command:

    $ docker-compose up

**Example Docker Compose File**

```yaml
version: '2.1'
services:
  web:
    image: alerta/alerta-web
    ports:
      - "8080:8080"
    depends_on:
      - db
    environment:
      - DEBUG=1  # remove this line to turn DEBUG off
      - DATABASE_URL=postgres://postgres:postgres@db:5432/monitoring
      - AUTH_REQUIRED=True
      - ADMIN_USERS=admin<EMAIL>,<EMAIL>
      - PLUGINS=reject,blackout,normalise,enhance
    restart: always
  db:
    image: postgres
    volumes:
      - ./pg-data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: monitoring
      POSTGRES_USER: postgres<commit_msg>add default admin password (#152)<commit_after>What is Alerta?
===============

The alerta monitoring system is a tool used to consolidate and
de-duplicate alerts from multiple sources for quick ‘at-a-glance’
visualisation. With just one system you can monitor alerts from
many other monitoring tools on a single screen.

How to use this image
=====================

To use this image run either a `mongo` or `postgres` container first:

    $ docker run --name alerta-db -d mongo

Then link to the database container when running the `alerta-web` container:

    $ export DATABASE_URL=mongodb://db:27017/monitoring
    $ docker run --name alerta-web -e DATABASE_URL=$DATABASE_URL --link alerta-db:db \
    -d -p <port>:8080 alerta/alerta-web

The API endpoint is at:

    http://<docker>:<port>/api

Browse to the alerta console at:

    http://<docker>:<port>/

Environment Variables
---------------------

The following environment variables are supported for configuring
the `alerta-web` container specifically for Docker deployments:

`ADMIN_PASSWORD`
    - sets the password of all admins. Should be changed at first login. default: alerta

`ADMIN_KEY`
    - sets an admin API key.

`HEARTBEAT_SEVERITY`
    - severity used to create alerts for stale heartbeats

The following environment variables are supported by the Alerta
API to ease deployment more generally:

`DEBUG`
    - debug mode for increased logging. (eg. `DEBUG=1`)

`BASE_URL`
    - used to make links in API responses relative. (default: `/api`)

`SECRET_KEY`
    - a unique, randomly generated sequence of ASCII characters.

`DATABASE_URL`
    - database connection URI string. Only MongoDB and Postgres allowed.

`DATABASE_NAME`
    - used to override database name in `DATABASE_URL`.

`AUTH_REQUIRED`
    - require users to authenticate when using web UI or `alerta` CLI.

`ADMIN_USERS`
    - comma-separated list of logins that will be created with "admin" role.

`CUSTOMER_VIEWS`
    - enable alert views partitioned by customer. (default:``False``)

`OAUTH2_CLIENT_ID`
    - client ID required by OAuth2 provider

`OAUTH2_CLIENT_SECRET`
    - client secret required by OAuth2 provider

`ALLOWED_EMAIL_DOMAINS`
    - list of authorised email domains when using Google

`GITHUB_URL`
    - GitHub Enteprise URL for privately run GitHub server

`ALLOWED_GITHUB_ORGS`
    - list of authorised GitHub organisations when using GitHub

`GITLAB_URL`
    - GitLab website URL for public or privately run GitLab server

`ALLOWED_GITLAB_GROUPS`
    - list of authorised GitLab groups when using GitLab

`KEYCLOAK_URL`
    - Keycloak URL

`KEYCLOAK_REALM`
    - Keycloak realm

`ALLOWED_KEYCLOAK_ROLES`
    - Keycloak roles

`CORS_ORIGINS`
    - list of URL origins that can access the API

`MAIL_FROM`
    - valid email address from which verification emails are sent

`SMTP_PASSWORD`
    - password for ``MAIL_FROM`` email account

`PLUGINS`
    - list of plugins to enable.

Configuration Files
-------------------

To set configuration settings not supported by environment variables use
configuration files instead. For example:

    $ docker run -v $PWD/config/alertad.conf:/app/alertad.conf \
      -v $PWD/config/config.json:/web/config.json \
      -p <port>:8080 alerta/alerta-web

For a full list of server configuration options see https://docs.alerta.io.

Plugins
-------

All built-in and contributed plugins are installed at image build time. Only
plugins listed in `PLUGINS` environment variabled will be enabled.

In the example below, of all the plugins installed only those listed will
be enabled at container start time:

    PLUGINS=remote_ip,reject,heartbeat,blackout,slack,prometheus

Custom plugins should be installed as an additional image layer.

Authentication
--------------

To make it easy to get going with Alerta on docker quickly, the default image
will use Basic Auth for user logins and login will be optional.

To allow users to login using Google OAuth, go to the [Google Developer Console][1]
and create a new client ID for a web application. Then set the `CLIENT_ID`
and `CLIENT_SECRET` environment variables on the command line as follows:

    $ export CLIENT_ID=379647311730-6tfdcopl5fodke08el52nnoj3x8mpl3.apps.googleusercontent.com
    $ export CLIENT_SECRET=<KEY>

Now pass in the defined environment variables to the `docker run` command:

    $ docker run --name alerta-web  -e PROVIDER=google -e CLIENT_ID=$CLIENT_ID \
    -e CLIENT_SECRET=$CLIENT_SECRET -d -p <port>:8080 alerta/alerta-web

This will allow users to login but will only make it optional. To enforce
users to login you must also set the `AUTH_REQUIRED` environment variable to
`True` when starting the docker image:

    $ docker run --name alerta-web -e AUTH_REQUIRED=True -e ...

To restrict logins to a certain email domain set the `ALLOWED_EMAIL_DOMAIN`
environment variable as follows:

    $ docker run --name alerta-web -e ALLOWED_EMAIL_DOMAIN=example.com ...

GitHub and GitLab can also be used as the OAuth2 providers by setting the
`PROVIDER` environment variable to `github` and `gitlab` respectively. For
more information on using GitHub, GitHub Enterprise or GitLab as th OAuth2
provider see https://docs.alerta.io

Docker Compose
--------------

Use `docker-compose` to create and start Alerta and Postgres with
one command:

    $ docker-compose up

**Example Docker Compose File**

```yaml
version: '2.1'
services:
  web:
    image: alerta/alerta-web
    ports:
      - "8080:8080"
    depends_on:
      - db
    environment:
      - DEBUG=1  # remove this line to turn DEBUG off
      - DATABASE_URL=postgres://postgres:postgres@db:5432/monitoring
      - AUTH_REQUIRED=True
      - ADMIN_USERS=<EMAIL>,<EMAIL> #default password: <PASSWORD>
      - PLUGINS=reject,blackout,normalise,enhance
    restart: always
  db:
    image: postgres
    volumes:
      - ./pg-data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: monitoring
      POSTGRES_USER: postgres
{'fraction_non_alphanumeric': 0.0874252505685168, 'fraction_numerical': 0.010528088941295376, 'mean_word_length': 3.5251524390243905, 'pattern_counts': {'":': 0, '<': 24, '<?xml version=': 0, '>': 24, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '582874', 'n_tokens_mistral': 3749, 'n_tokens_neox': 3568, 'n_words': 1366}