From cc50e13912adb1a8f8b86ea93c30b1fd3596c8be 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 docs: fix Icinga Web naming --- doc/01-About.md | 26 ++++++++++ doc/02-Installation.md | 16 ++++++ doc/02-Installation.md.d/From-Source.md | 22 +++++++++ doc/03-Configuration.md | 65 +++++++++++++++++++++++++ 4 files changed, 129 insertions(+) diff --git a/doc/01-About.md b/doc/01-About.md index e69de29bb..19f066c7f 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: + +* An [Icinga Notifications Daemon](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..4b953dcc1 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 the +[Icinga Notifications Daemon](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..7e5558a01 100644 --- a/doc/02-Installation.md.d/From-Source.md +++ b/doc/02-Installation.md.d/From-Source.md @@ -0,0 +1,22 @@ +# 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: + - `cURL` + - `dom` + - `json` + - `libxml` +- [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 Daemon](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..fa4618a8b 100644 --- a/doc/03-Configuration.md +++ b/doc/03-Configuration.md @@ -0,0 +1,65 @@ +# 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, +the [Icinga Notifications Daemon](https://github.com/Icinga/icinga-notifications) and the [Icinga Notifications Web +Module](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. +Currently, the following technologies are supported: + +- E-Mail (SMTP) +- Rocket.Chat +- Webhook + +You need to configure at least one valid communication channel to be able to provide your contacts 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 the + [Icinga Notifications Daemon](https://github.com/Icinga/icinga-notifications) to check for the certificate + validity of the given REST API endpoint.