From 16926db5f884267e0fc4e934e8ae64a5bbf25350 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9=20Costa?= Date: Tue, 25 Jun 2024 18:44:15 +0200 Subject: [PATCH] docs: build instructions, about, installation and configuration steps --- doc/01-About.md | 24 ++++++++++ doc/02-Installation.md | 16 +++++++ doc/02-Installation.md.d/From-Source.md | 19 ++++++++ doc/03-Configuration.md | 62 +++++++++++++++++++++++++ 4 files changed, 121 insertions(+) diff --git a/doc/01-About.md b/doc/01-About.md index e69de29b..2e41365e 100644 --- a/doc/01-About.md +++ b/doc/01-About.md @@ -0,0 +1,24 @@ +# 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 and any other sources propagate state updates and other events +to [Icinga Notifications](https://github.com/Icinga/icinga-notifications). + +## Installation + +To install Icinga Notifications Web see [Installation](02-Installation.md). + +## License + +Icinga Notifications and the Icinga Notifications Web documentation are licensed under the terms of the +GNU General Public License Version 2. diff --git a/doc/02-Installation.md b/doc/02-Installation.md index e69de29b..0964cea7 100644 --- a/doc/02-Installation.md +++ b/doc/02-Installation.md @@ -0,0 +1,16 @@ + + +# 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). + + + +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..9f7bfc7a 100644 --- a/doc/03-Configuration.md +++ b/doc/03-Configuration.md @@ -0,0 +1,62 @@ +# 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: + +- Access the command-line interface on your master(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 module notifies contacts in case of events and incidents, you need to configure appropriate +communication channels. + +The currently supported channels can be found in the [Icinga Notifications documentation](https://icinga.com/docs/icinga-notifications/latest/doc/10-Channels#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 + +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 Icinga 2 API credentials with the following + [permissions](https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#overview): + - events/* + - objects/query/* +3. Enable `Verify API Certificate` if you want + [Icinga Notifications](https://github.com/Icinga/icinga-notifications) to check for the certificate + validity of the given REST API endpoint.