Recommend package installs & enhance installation & configuration docs (

#204) fixes #196
Icinga · Oct 17, 2023 · 6af246f · 6af246f
2 parents a856edd + 301c869
commit 6af246f
Show file tree

Hide file tree

Showing 4 changed files with 112 additions and 66 deletions.
diff --git a/doc/01-About.md b/doc/01-About.md
@@ -0,0 +1,18 @@
+# Icinga Reporting
+
+Icinga Reporting is the central component for reporting related functionality in the monitoring web frontend and
+framework Icinga Web. The engine allows you to create reports over a specified time period for ad-hoc and scheduled
+generation of reports. Other modules use the provided functionality in order to provide concrete reports.
+
+## Host/Service SLA Reports
+
+With Icinga DB Web there is no additional module required.
+
+If you are still using the monitoring module, please also install the
+[idoreports](https://icinga.com/docs/icinga-reporting/latest/idoreports/doc/02-Installation/) module.
+
+## Documentation
+
+* [Installation](02-Installation.md)
+* [Configuration](03-Configuration.md)
+* [Upgrading](80-Upgrading.md)
diff --git a/doc/02-Installation.md b/doc/02-Installation.md
@@ -1,41 +1,56 @@
-# Installation
+<!-- {% if index %} -->
+# Installing Icinga Reporting
 
-## Requirements
+The recommended way to install Icinga Reporting and its dependencies is to use prebuilt packages for all supported
+platforms from our official release repository. Please note that [Icinga Web](https://icinga.com/docs/icinga-web) is
+required and if it is not already set up, it is best to do this first.
 
-* PHP (>= 7.0)
-* Icinga Web 2 (>= 2.9)
-* Icinga Web 2 libraries:
-  * [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.12)
-  * [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (>= 0.10)
-* Icinga Web 2 modules:
-  * [Icinga PDF Export](https://github.com/Icinga/icingaweb2-module-pdfexport) (>= 0.10)
-* MySQL / MariaDB or PostgreSQL
-* php-mbstring
+To upgrade an existing Icinga Reporting installation to a newer version, see the [Upgrading](80-Upgrading.md) documentation
+for the necessary steps.
+<!-- {% else %} -->
+<!-- {% if not icingaDocs %} -->
 
-## Database Setup
+## Installing the Package
 
-### MySQL / MariaDB
+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-reporting` package
+or install [from source](02-Installation.md.d/From-Source.md).
+<!-- {% endif %} -->
 
-The module needs a MySQL/MariaDB database with the schema that's provided in the `etc/schema/mysql.schema.sql` file.
+## Setting up the Database
 
-Example command for creating the MySQL/MariaDB database. Please change the password:
+### Setting up a MySQL or MariaDB Database
+
+The module needs a MySQL/MariaDB database with the schema that's provided in the `/usr/share/icingaweb2/modules/reporting/schema/mysql.schema.sql` file.
+<!-- {% if not icingaDocs %} -->
+
+**Note:** If you haven't installed this module from packages, then please adapt the schema path to the correct installation path.
+
+<!-- {% endif %} -->
+
+You can use the following sample command for creating the MySQL/MariaDB database. Please change the password:
 
 ```
 CREATE DATABASE reporting;
-GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE, CREATE VIEW, INDEX, EXECUTE ON reporting.* TO reporting@localhost IDENTIFIED BY 'secret';
+GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, CREATE VIEW, INDEX, EXECUTE ON reporting.* TO reporting@localhost IDENTIFIED BY 'secret';
 ```
 
 After, you can import the schema using the following command:
 
 ```
-mysql -p -u root reporting < schema/mysql.schema.sql
+mysql -p -u root reporting < /usr/share/icingaweb2/modules/reporting/schema/mysql.schema.sql
 ```
 
-## PostgreSQL
+## Setting up a PostgreSQL Database
+
+The module needs a PostgreSQL database with the schema that's provided in the `/usr/share/icingaweb2/modules/reporting/schema/pgsql.schema.sql` file.
+<!-- {% if not icingaDocs %} -->
 
-The module needs a PostgreSQL database with the schema that's provided in the `etc/schema/pgsql.schema.sql` file.
+**Note:** If you haven't installed this module from packages, then please adapt the schema path to the correct installation path.
 
-Example command for creating the PostgreSQL database. Please change the password:
+<!-- {% endif %} -->
+
+You can use the following sample command for creating the PostgreSQL database. Please change the password:
 
 ```sql
 CREATE USER reporting WITH PASSWORD 'secret';
@@ -49,36 +64,8 @@ CREATE DATABASE reporting
 After, you can import the schema using the following command:
 
 ```
-psql -U reporting reporting -a -f schema/pgsql.schema.sql
+psql -U reporting reporting -a -f /usr/share/icingaweb2/modules/reporting/pgsql.schema.sql
 ```
 
-## Module Installation
-
-1. Install it [like any other module](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation).
-Use `reporting` as name.
-
-2. Once you've set up the database, create a new Icinga Web 2 resource for it using the
-`Configuration -> Application -> Resources` menu. Make sure that you set the character set to `utf8mb4`.
-
-3. The next step involves telling the Reporting module which database resource to use. This can be done in
-`Configuration -> Modules -> reporting -> Backend`. If you've used `reporting` as name for the resource,
-you can skip this step.
-
 This concludes the installation. Now continue with the [configuration](03-Configuration.md).
-
-## Scheduler Daemon
-
-There is a daemon for generating and distributing reports on a schedule if configured:
-
-```
-icingacli reporting schedule run
-```
-
-This command schedules the execution of all applicable reports.
-
-You may configure this command as `systemd` service. Just copy the example service definition from
-`config/systemd/icinga-reporting.service` to `/etc/systemd/system/icinga-reporting.service` and enable it afterwards:
-
-```
-systemctl enable icinga-reporting.service
-```
+<!-- {% endif %} --><!-- {# end else if index #} -->
diff --git a/doc/02-Installation.md.d/From-Source.md b/doc/02-Installation.md.d/From-Source.md
@@ -0,0 +1,16 @@
+# Installing Icinga Reporting 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 `reporting` as the module name. The following requirements must also be met.
+
+## Requirements
+
+* PHP (≥7.2)
+* MySQL or PostgreSQL PDO PHP libraries
+* The following PHP modules must be installed: `mbstring`
+* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.9)
+* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.13.0)
+* [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (≥0.12.0)
+
+<!-- {% include "02-Installation.md" %} -->
diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md
@@ -1,20 +1,17 @@
 # Configuration
 
-1. [Backend](#backend)
-2. [Mail](#mail)
-3. [Permissions](#permissions)
+Icinga Reporting is configured via the web interface. Below you will find an overview of the necessary settings.
 
 ## Backend
 
-If not already done during the installation of Icinga Reporting, setup the reporting database backend now.
+Icinga Reporting stores all its configuration in the database, therefore you need to create and configure a database
+resource for it.
 
-Create a new [Icinga Web 2 resource](https://icinga.com/docs/icingaweb2/latest/doc/04-Resources/#database)
-for [Icinga Reporting's database](https://icinga.com/docs/icinga-reporting/latest/doc/02-Installation/#database-setup)
-using the `Configuration -> Application -> Resources` menu.
+1. Create a new resource for Icinga Reporting via the `Configuration -> Application -> Resources` menu.
 
-Then tell Icinga Reporting which database resource to use. This can be done in
-`Configuration -> Modules -> reporting -> Backend`. If you've used `reporting`
-as name for the resource, this is optional.
+2. Configure the resource you just created as the database connection for Icinga Reporting using the
+   `Configuration → Modules → reporting → Backend` menu. If you've used `reporting`
+   as name for the resource, this is optional.
 
 ## Mail
 
@@ -25,9 +22,37 @@ that is used as the sender's address (From) in E-mails.
 
 There are four permissions that can be used to control what can be managed by whom.
 
-Permission           | Applies to
----------------------|----------------
-reporting/reports    | Reports (create, edit, delete)
-reporting/schedules  | Schedules (create, edit, delete)
-reporting/templates  | Templates (create, edit, delete)
-reporting/timeframes | Timeframes (create, edit, delete)
+| Permission           | Applies to                        |
+|----------------------|-----------------------------------|
+| reporting/reports    | Reports (create, edit, delete)    |
+| reporting/schedules  | Schedules (create, edit, delete)  |
+| reporting/templates  | Templates (create, edit, delete)  |
+| reporting/timeframes | Timeframes (create, edit, delete) |
+
+## Icinga Reporting Daemon
+
+There is a daemon for generating and distributing reports on a schedule if configured:
+
+```
+icingacli reporting schedule run
+```
+
+This command schedules the execution of all applicable reports.
+
+The default `systemd` service of this module, shipped with package installations, uses this command as well.
+
+<!-- {% 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/reporting/config/systemd/icinga-reporting.service`
+> to `/etc/systemd/system/icinga-reporting.service`.
+
+<!-- {% endif %} -->
+
+You can run the following command to enable and start the daemon.
+
+```
+systemctl enable --now icinga-reporting.service
+```