From 620e240143da042fe560220cb5eadb6d5f7b93af 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 | 26 +++++++++++ doc/02-Installation.md | 16 +++++++ doc/02-Installation.md.d/From-Source.md | 19 ++++++++ doc/03-Configuration.md | 61 +++++++++++++++++++++++++ 4 files changed, 122 insertions(+) diff --git a/doc/01-About.md b/doc/01-About.md index e69de29bb..4b98a646f 100644 --- a/doc/01-About.md +++ b/doc/01-About.md @@ -0,0 +1,26 @@ +# 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 the [Icinga Notifications +Daemon](https://github.com/Icinga/icinga-notifications). + +![Icinga Notifications Web Preview](res/notifications-preview.png) + +## Installation + +To install Icinga Notifications Web see [Installation](02-Installation.md). + +## License + +Icinga Notifications and the Icinga Notifications 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 e69de29bb..0964cea7c 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 e69de29bb..9b80d5a1a 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 e69de29bb..4bbb3fd4c 100644 --- a/doc/03-Configuration.md +++ b/doc/03-Configuration.md @@ -0,0 +1,61 @@ +# Configuration + +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 Icinga 2 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 this 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. +Though, any other external system needs to +respect [a specific data structure when providing its own data](https://icinga.com/docs/icinga-notifications/latest/doc/02-Installation#process-event). + +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.