doc: Initialize documentation

Both structure and huge parts are copied from Icinga DB and were altered
afterwards. The already existing Channel Plugin documentation was
extended.

Makefile

@@ -1,7 +1,7 @@
 # These variables follow the naming convention from the GNU Make documentation
 # but their defaults correspond to the rest of the code (note that changing
 # libexecdir here wouldn't affect the default path for the channel plugin
-# directory used by the dameon for example).
+# directory used by the daemon for example).
 #
 # https://www.gnu.org/software/make/manual/html_node/Directory-Variables.html
 prefix     ?= /usr

README.md

@@ -1,40 +1,19 @@
 # Icinga Notifications
 
-> **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 yet provide any support for this.
+> [!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 yet provide any support for this.
 
-Icinga Notifications is a set of components that processes received events from various sources, manages incidents and
-forwards notifications to predefined contacts, consisting of:
+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 (this repository), which receives events and sends notifications
-* An [Icinga Web module](https://github.com/Icinga/icinga-notifications-web) 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
+* The Icinga Notifications daemon (this repository), which receives events and sends notifications.
+* An [Icinga Web module](https://github.com/Icinga/icinga-notifications-web) that provides graphical configuration and further processing of the data collected by the daemon.
+* Icinga 2 or another sources that provides monitoring events leading to notifications.
 
-## Installation
-
-To install Icinga Notifications and get started, you first need to clone this repository.
-```bash
-git clone https://github.com/Icinga/icinga-notifications.git
-```
-
-Next, you need to provide a `config.yml` file, similar to the [example config](config.example.yml), for the daemon.
-It is required that you have created a new database and imported the [schema](schema/pgsql/schema.sql) file beforehand.
-> **Note**
-> At the moment **PostgreSQL** is the only database backend we support.
-
-Additionally, it also requires you to manually insert items into the **source** table before starting the daemon.
-```sql
-INSERT INTO source
-    (id, type, name, icinga2_base_url, icinga2_auth_user, icinga2_auth_pass, icinga2_insecure_tls)
-VALUES
-    (1, 'icinga2', 'Local Icinga 2', 'https://localhost:5665', 'root', 'icinga', 'y');
-```
-
-Then, you can launch the daemon with the following command.
-```go
-go run ./cmd/icinga-notifications --config config.yml
-```
+For more information about how to install or use Icinga Notifications,
+just follow the [documentation](https://icinga.com/docs/icinga-notifications/latest).
 
 ## License
 

doc/01-About.md

@@ -0,0 +1,41 @@
+# Icinga Notifications
+
+!!! 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 yet provide any support for this.
+
+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 (this repository), which receives events and sends notifications.
+* An [Icinga Web module](https://github.com/Icinga/icinga-notifications-web) that provides graphical configuration and further processing of the data collected by the daemon.
+* Icinga 2 or another sources that provides monitoring events leading to notifications.
+
+## Big Picture
+
+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 the Icinga Notifications Web.
+
+Depending on its configuration, the daemon will take further action on these events.
+This optionally includes escalations that are sent through a channel plugin.
+Each such channel plugin 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.
+
+## Installation
+
+To install Icinga Notifications 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.

doc/02-Installation.md

@@ -0,0 +1,120 @@
+<!-- {% if index %} -->
+# Installing Icinga Notifications
+
+The recommended way to install Icinga Notifications 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.
+
+To upgrade an existing Icinga Notifications installation to a newer version,
+see the [Upgrading](04-Upgrading.md) documentation for the necessary steps.
+
+<!-- {% else %} -->
+
+## Setting up the Database
+
+A MySQL (≥5.5), MariaDB (≥10.1), or PostgreSQL (≥9.6) database is required to run Icinga Notifications.
+Please follow the steps listed for your target database,
+which guide you through setting up the database and user and importing the schema.
+
+### Setting up a MySQL or MariaDB Database
+
+If you use a version of MySQL < 5.7 or MariaDB < 10.2, the following server options must be set:
+
+```
+innodb_file_format=barracuda
+innodb_file_per_table=1
+innodb_large_prefix=1
+```
+
+Set up a MySQL database for Icinga Notifications:
+
+```
+# mysql -u root -p
+
+CREATE DATABASE notifications;
+CREATE USER 'notifications'@'localhost' IDENTIFIED BY 'CHANGEME';
+GRANT ALL ON notifications.* TO 'notifications'@'localhost';
+```
+
+After creating the database, import the Icinga Notifications schema using the following command:
+
+```
+mysql -u root -p notifications < /usr/share/icinga-notifications/schema/mysql/schema.sql
+```
+
+### Setting up a PostgreSQL Database
+
+Set up a PostgreSQL database for Icinga Notifications:
+
+```
+# su -l postgres
+
+createuser -P notifications
+createdb -E UTF8 --locale en_US.UTF-8 -T template0 -O notifications notifications
+echo 'CREATE EXTENSION IF NOT EXISTS citext;' | psql notifications
+```
+
+The `CREATE EXTENSION` command requires the `postgresql-contrib` package.
+
+Edit `pg_hba.conf`, insert the following before everything else:
+
+```
+local all notifications           md5
+host  all notifications 0.0.0.0/0 md5
+host  all notifications      ::/0 md5
+```
+
+To apply these changes, run `systemctl reload postgresql`.
+
+After creating the database, import the Icinga Notifications schema using the following command:
+
+```
+psql -U icinga-notifications notifications < /usr/share/icinga-notifications/schema/pgsql/schema.sql
+```
+
+## Configuring Icinga Notifications
+
+Icinga Notifications installs its configuration file to `/etc/icinga-notifications/config.yml`,
+pre-populating most of the settings for a local setup. Before running Icinga Notifications,
+adjust the database credentials and the Icinga Web 2 URL.
+The configuration file explains general settings.
+All available settings can be found under [Configuration](03-Configuration.md).
+
+## Configuring Icinga 2
+
+Icinga Notifications utilizes the [Icinga 2 API](https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/)
+to fetch events from an Icinga 2 instance.
+Thus, if the Icinga 2 API is not already configured,
+please follow the [API setup guide](https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#setting-up-the-api) now.
+Furthermore, an [`ApiUser`](https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#objecttype-apiuser)
+with [permissions](https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#icinga2-api-permissions)
+as listed in the example below is required.
+
+```
+object ApiUser "notifications" {
+  password = "insecure"
+  permissions = [ "events/*", "objects/query/*" ]
+}
+```
+
+After completing setting up Icinga Notifications Web, the Icinga 2 API can be configured with this `ApiUser` as a source.
+
+## Running Icinga Notifications
+
+The `icinga-notifications` package automatically installs the necessary systemd unit files to run Icinga Notifications.
+Please run the following command to enable and start its service:
+
+```
+systemctl enable --now icinga-notifications
+```
+
+## Installing Icinga Notifications Web
+
+With Icinga 2, Icinga Notifications and the database fully set up, it is now time to install Icinga Notifications Web,
+which connects to the database and allows configuring Icinga Notifications.
+
+Please follow the
+[Icinga Notifications Web documentation](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/).
+
+<!-- {% endif %} --><!-- {# end else if index #} -->

doc/02-Installation.md.d/From-Source.md

@@ -0,0 +1,10 @@
+# Installing Icinga Notifications from Source
+
+Although the provided packages are highly recommended and are the only officially supported installation,
+it may be necessary to build the software manually, e.g., if there are no packages available for the target platform.
+
+Please follow the build instructions in the [development section](../30-Development.md)
+for more information about requirements and the `Makefile`-based build.
+
+<!-- {% set from_source = True %} -->
+<!-- {% include "02-Installation.md" %} -->