From 8b4ce428f099c2e28c6aa397ffed22527b03ea28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9=20Costa?= Date: Fri, 5 Jul 2024 19:29:55 +0200 Subject: [PATCH] docs: build instructions, about, installation and configuration steps --- doc/01-About.md | 54 ++++++++++++++++++++ doc/02-Installation.md | 26 ++++++++++ doc/02-Installation.md.d/From-Source.md | 19 +++++++ doc/03-Configuration.md | 67 +++++++++++++++++++++++++ 4 files changed, 166 insertions(+) diff --git a/doc/01-About.md b/doc/01-About.md index e69de29b..2444f980 100644 --- a/doc/01-About.md +++ b/doc/01-About.md @@ -0,0 +1,54 @@ +# Icinga Notifications Web + +!!! warning + This is an early beta version for you to try, but do not use this in production. There may still be severe bugs. + + At the moment, we don't provide any support for this module. + +Icinga Notifications is a set of components that processes received events from miscellaneous sources, manages +incidents and forwards notifications to predefined contacts, consisting of: + +* [Icinga Notifications](https://github.com/Icinga/icinga-notifications), which receives events and sends notifications. +* Icinga Notifications Web, which provides graphical configuration. + +Icinga 2 itself and other sources propagate state updates and other events to [Icinga Notifications](https://github.com/Icinga/icinga-notifications). + +## Big Picture + +![Icinga Notifications Architecture](res/notifications-architecture.png) + +Because Icinga Notifications consists of several components, +this section tries to help understand how these components relate. + +First, the Icinga Notifications configuration resides in a SQL database. +It can be conveniently tweaked via Icinga Notifications Web directly from a web browser. +The Icinga Notifications daemon uses this database to read the current configuration. + +As in any Icinga setup, all host and service checks are defined in Icinga 2. +By querying the Icinga 2 API, the Icinga Notifications daemon retrieves state changes, acknowledgements and other events. +These events are stored in the database and are available for further inspection in Icinga Notifications Web. +Next to Icinga 2, other notification sources can be configured. + +Depending on its configuration, the daemon will take action on these events. +This optionally includes escalations that are sent through a channel plugin. +Each of those channel plugins implements a domain-specific transport, e.g., the `email` channel sends emails via SMTP. +When configured, Icinga Notifications will use channel plugins to notify end users or talk to other APIs. + +## Available Channels + +Icinga Notifications comes with multiple channels out of the box: + +* _email_: Email submission via SMTP +* _rocketchat_: Rocket.Chat +* _webhook_: Configurable HTTP/HTTPS queries for third-party backends + +Additional custom channels can be developed independently of Icinga Notifications, +following the [channel specification](https://icinga.com/docs/icinga-notifications/latest/doc/10-Channels). + +## Installation + +To install Icinga Notifications Web see [Installation](02-Installation.md). + +## License + +Icinga Notifications Web and its documentation are licensed under the terms of the [GNU General Public License Version 2](https://github.com/Icinga/icinga-notifications-web?tab=GPL-2.0-1-ov-file#readme). diff --git a/doc/02-Installation.md b/doc/02-Installation.md index e69de29b..193a1107 100644 --- a/doc/02-Installation.md +++ b/doc/02-Installation.md @@ -0,0 +1,26 @@ + + +# Installing Icinga Notifications Web + +The recommended way to install Icinga Notifications Web is to use prebuilt packages for +all supported platforms from our official release repository. + +Please follow the steps listed for your target operating system, +which guide you through setting up the repository and installing Icinga Notifications Web. + +Before installing Icinga Notifications Web, make sure you have installed +[Icinga Notifications](https://icinga.com/docs/icinga-notifications/latest/doc/02-Installation). + + + + + +## Installing the Package + +If the [repository](https://packages.icinga.com) is not configured yet, please add it first. +Then use your distribution's package manager to install the `icinga-notifications-web` package +or install [from source](02-Installation.md.d/From-Source.md). + + +This concludes the installation. Now proceed with the [configuration](03-Configuration.md). + diff --git a/doc/02-Installation.md.d/From-Source.md b/doc/02-Installation.md.d/From-Source.md index e69de29b..9b80d5a1 100644 --- a/doc/02-Installation.md.d/From-Source.md +++ b/doc/02-Installation.md.d/From-Source.md @@ -0,0 +1,19 @@ +# Installing Icinga Notifications Web from Source + +Please see the Icinga Web documentation on +[how to install modules](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation) from source. +Make sure you use `notifications` as the module name. The following requirements must also be met. + +### Requirements + +- PHP (≥7.2) +- PHP needs the following extensions to be installed and activated: + - `json` +- [MySQL](https://www.php.net/manual/en/ref.pdo-mysql.php) + or [PostgreSQL](https://www.php.net/manual/en/ref.pdo-pgsql.php) PDO PHP libraries +- [Icinga Notifications](https://github.com/Icinga/icinga-notifications) +- [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.9) +- [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.12.0) +- [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (≥0.11.0) + + diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md index e69de29b..00b34e3d 100644 --- a/doc/03-Configuration.md +++ b/doc/03-Configuration.md @@ -0,0 +1,67 @@ +# Configuration + +![Icinga Notifications Web Preview](res/notifications-preview.png) + +If Icinga Web has been installed but not yet set up, please visit Icinga Web and follow the web-based setup wizard. +For Icinga Web setups already running, log in to Icinga Web with a privileged user and follow the steps below to +configure Icinga Notifications Web: + + + +## Module Activation + +If you just installed the module, do not forget to activate it on your Icinga Web instance(s) by using your +preferred way: + +- Use Icinga Web's command-line interface on the webserver(s) and execute `icingacli module enable notifications`. +- Visit Icinga Web, log in as a privileged user and activate the module under `Configuration → + Modules → Notifications` by switching the state from `disabled` to `enabled`. + + + +## Database Configuration + +Connection configuration for the database, which both, +[Icinga Notifications](https://github.com/Icinga/icinga-notifications) and [Icinga Notifications Web](https://github.com/Icinga/icinga-notifications-web), use. + +!!! tip + If not already done, initialize your database by following the [instructions](https://icinga.com/docs/icinga-notifications/latest/doc/02-Installation#setting-up-the-database). + +1. Create a new resource for the Icinga Notifications database via the `Configuration → Application → Resources` menu. +2. Configure the resource you just created as the database connection for the Icinga Notifications Web module using the + `Configuration → Modules → notifications → Database` menu. + +## Channels Configuration + +As the Icinga Notifications daemon notifies contacts in case of events and incidents, you need to configure appropriate +communication channels. + +The currently supported channels can be found [here](01-About.md#available-channels). + +You need to configure at least one valid communication channel to be able to supply your contacts with notifications. + +## Sources Configuration + +The notifications module operates on data fed by miscellaneous sources and is therefore not restricted to Icinga 2 only. +Consult the source specific documentation on how to integrate such. + +You need to provide at least one valid source for this module to function properly. + +### Adding an Icinga 2 source + +!!! tip + If there is no API user with the required permissions yet, read through [Icinga Web's API documentation](https://icinga.com/docs/icinga-web/latest/modules/monitoring/doc/05-Command-Transports/#use-the-icinga-2-api). + + The API user needs the following [permissions](https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#overview): + + - `events/*` + + - `objects/query/*` + +If you want the notifications module to process Icinga 2 events, you will need to add it as a source: + +1. Navigate to `Configuration → Module → notifications → Sources` and add a new source. +2. Choose type `Icinga` and provide the Icinga 2 API credentials. +3. Enable `Verify API Certificate` if you want + [Icinga Notifications](https://icinga.com/docs/icinga-notifications/latest) to check for the certificate + validity of the given REST API endpoint.