docs: build instructions, about, installation and configuration steps

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).

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,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:
+
+<!-- {% 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).
+
+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.