Add documentation (#218)

This PR includes basic documentation for the current state of the
module.

resolves #206

README.md

@@ -1,39 +1,58 @@
 # Icinga Notifications Web
 
-> **Warning**
->
-> This is an early preview version for you to try, but do not use this in production. There may still be severe bugs
-> and incompatible changes may happen without any notice. At the moment, we don't provide any support for this.
+[![PHP Support](https://img.shields.io/badge/php-%3E%3D%207.2-777BB4?logo=PHP)](https://php.net/)
+![Build Status](https://github.com/Icinga/icinga-notifications-web/actions/workflows/php.yml/badge.svg?branch=main)
+[![Github Tag](https://img.shields.io/github/tag/Icinga/icinga-notifications-web.svg)](https://github.com/Icinga/icinga-notifications-web/releases/latest)
+
+> [!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 various sources, manages incidents and
 forwards notifications to predefined contacts, consisting of:
 
-* The [Icinga Notifications daemon](https://github.com/Icinga/icinga-notifications), which receives events and sends notifications
-* An Icinga Web module (this repository), that provides graphical configuration and further processing of the data collected by the daemon
-* And Icinga 2 and other custom sources that propagate state updates and acknowledgement events to the daemon
+* [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 miscellaneous other sources propagate state updates and other events to [Icinga Notifications](https://github.com/Icinga/icinga-notifications).
+
+## Big Picture
+
+![Icinga Notifications Architecture](doc/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.
 
-## Installation
+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.
 
-First, install the [daemon](https://github.com/Icinga/icinga-notifications).
+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.
 
-Then install this like any other [module](https://icinga.com/docs/icinga-web/latest/doc/08-Modules/). Use `notifications` as name.
+## Available Channels
 
-## Configuration
+Icinga Notifications comes with multiple channels out of the box:
 
-After you have enabled the module, create a new database resource pointing to the database you have created
-during the installation process of the daemon. Then choose it as the backend for the module at:
-`Configuration -> Modules -> notifications -> Database (Tab)`
+* _email_: Email submission via SMTP
+* _rocketchat_: Rocket.Chat
+* _webhook_: Configurable HTTP/HTTPS queries for third-party backends
 
-Your next step should be to set up the channels you want to use to send notifications over. You do this at:
-`Configuration -> Modules -> notifications -> Channels (Tab)`.
+Additional custom channels can be developed independently of Icinga Notifications,
+following the [channel specification](https://icinga.com/docs/icinga-notifications/latest/doc/10-Channels).
 
-> **Note**
->
-> Make sure the **daemon** is able to connect to the SMTP host or Rocket.Chat Instance!
+## Documentation
 
-The base configuration is now done. You can continue now by setting up your first contacts, event rules and schedules!
-You do this at: `Notifications -> Configuration`
+Icinga Notifications Web documentation is available at [icinga.com/docs](https://icinga.com/docs/icinga-notifications-web/latest).
 
 ## License
 
-Icinga Notifications is licensed under the terms of the [GNU General Public License Version 2](LICENSE).
+Icinga Notifications Web and its documentation are licensed under the terms of the [GNU General Public License Version 2](LICENSE).

doc/01-About.md

@@ -0,0 +1,55 @@
+# 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).

doc/02-Installation.md

@@ -0,0 +1,26 @@
+<!-- {% if index %} -->
+
+# 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).
+
+<!-- {% else %} -->
+
+<!-- {% if not icingaDocs %} -->
+
+## 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).
+<!-- {% endif %} -->
+
+This concludes the installation. Now proceed with the [configuration](03-Configuration.md).
+<!-- {% endif %} -->

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)
+
+<!-- {% include "02-Installation.md" %} -->

doc/03-Configuration.md

@@ -0,0 +1,72 @@
+# 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:
+
+<!-- {% if not icingaDocs %} -->
+
+## 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`.
+
+<!-- {% endif %} -->
+
+## 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).
+
+They can be configured through `Configuration → Modules → notifications → Channels` and the credentials to be supplied 
+might differ depending on the channel type.
+
+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's API documentation](https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#authentication).
+
+    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. (Optional) Disable `Verify API Certificate` if you want
+   [Icinga Notifications](https://icinga.com/docs/icinga-notifications/latest) to skip its check for the certificate
+   validity of the given REST API endpoint.

doc/06-Desktop-Notifications.md

@@ -3,10 +3,11 @@
 With Icinga Notifications, users are able to enable desktop notifications which will inform them about severity
 changes in incidents they are notified about.
 
-> **Note**
->
-> This feature is currently considered experimental and might not work as expected in all cases.
-> We will continue to improve this feature in the future. Your feedback is highly appreciated.
+!!! Note
+
+    This feature is currently considered experimental and might not work as expected in all cases.
+
+    We will continue to improve this feature in the future. Your feedback is highly appreciated.
 
 ## How It Works
 
@@ -81,23 +82,25 @@ location ~ ^/icingaweb2/notifications/v(\d+)/subscribe$ {
 }
 ```
 
-> **Note**
->
-> Since these connections are long-lived, the default web server configuration might impose a too small limit on
-> the maximum number of connections. Make sure to adjust this limit to a higher value. If working correctly, the
-> daemon will limit the number of connections per client to 2.
+!!! Note
+
+    Since these connections are long-lived, the default web server configuration might impose a too small limit on
+    the maximum number of connections. Make sure to adjust this limit to a higher value.
+
+    If working correctly, the daemon will limit the number of connections per client to 2.
 
 ### Enable The Daemon
 
 The default `systemd` service, shipped with package installations, runs the background daemon.
 
 <!-- {% if not icingaDocs %} -->
 
-> **Note**
->
-> If you haven't installed this module from packages, you have to configure this as a `systemd` service yourself by just
-> copying the example service definition from `/usr/share/icingaweb2/modules/notifications/config/systemd/icinga-desktop-notifications.service`
-> to `/etc/systemd/system/icinga-desktop-notifications.service`.
+!!! Note
+
+    If you haven't installed this module from packages, you have to configure this as a `systemd` service yourself by just
+    copying the example service definition from `/usr/share/icingaweb2/modules/notifications/config/systemd/icinga-desktop-notifications.service`
+    to `/etc/systemd/system/icinga-desktop-notifications.service`.
+
 <!-- {% endif %} -->
 
 You can run the following command to enable and start the daemon.