summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/02-Installation.md83
-rw-r--r--doc/03-Configuration.md33
-rw-r--r--doc/80-Upgrading.md18
3 files changed, 134 insertions, 0 deletions
diff --git a/doc/02-Installation.md b/doc/02-Installation.md
new file mode 100644
index 0000000..fe4b8e4
--- /dev/null
+++ b/doc/02-Installation.md
@@ -0,0 +1,83 @@
+# Installation
+
+## Requirements
+
+* PHP (>= 7.0)
+* Icinga Web 2 (>= 2.9)
+* Icinga Web 2 libraries:
+ * [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.8)
+ * [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
+
+## Database Setup
+
+### MySQL / MariaDB
+
+The module needs a MySQL/MariaDB database with the schema that's provided in the `etc/schema/mysql.sql` file.
+
+Example command for creating the MySQL/MariaDB database. Please change the password:
+
+```
+CREATE DATABASE reporting;
+GRANT SELECT, INSERT, UPDATE, DELETE, DROP, 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.sql
+```
+
+## PostgreSQL
+
+The module needs a PostgreSQL database with the schema that's provided in the `etc/schema/postgresql.sql` file.
+
+Example command for creating the PostgreSQL database. Please change the password:
+
+```sql
+CREATE USER reporting WITH PASSWORD 'secret';
+CREATE DATABASE reporting
+ WITH OWNER reporting
+ ENCODING 'UTF8'
+ LC_COLLATE = 'en_US.UTF-8'
+ LC_CTYPE = 'en_US.UTF-8';
+```
+
+After, you can import the schema using the following command:
+
+```
+psql -U reporting reporting -a -f schema/postgresql.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
+```
diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md
new file mode 100644
index 0000000..f06481c
--- /dev/null
+++ b/doc/03-Configuration.md
@@ -0,0 +1,33 @@
+# Configuration
+
+1. [Backend](#backend)
+2. [Mail](#mail)
+3. [Permissions](#permissions)
+
+## Backend
+
+If not already done during the installation of Icinga Reporting, setup the reporting database backend now.
+
+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.
+
+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.
+
+## Mail
+
+At `Configuration -> Modules -> reporting -> Mail` you can configure the address
+that is used as the sender's address (From) in E-mails.
+
+## Permissions
+
+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)
diff --git a/doc/80-Upgrading.md b/doc/80-Upgrading.md
new file mode 100644
index 0000000..8252e6f
--- /dev/null
+++ b/doc/80-Upgrading.md
@@ -0,0 +1,18 @@
+# Upgrading Icinga Reporting <a id="upgrading"></a>
+
+Upgrading Icinga Reporting is straightforward.
+Usually the only manual steps involved are schema updates for the database.
+
+## Upgrading to Version 0.9.1 <a id="upgrading-to-v0.9.1"></a>
+
+Icinga Reporting version 0.9.1 requires a schema update for the database.
+The schema has been adjusted so that it is no longer necessary to adjust server settings
+if you're using a version of MySQL < 5.7 or MariaDB < 10.2.
+Further, the start dates for the provided time frames **Last Year** and **Current Year** have been fixed.
+Please find the upgrade script in **schema/mysql-migrations**.
+
+You may use the following command to apply the database schema upgrade file:
+
+```
+# mysql -u root -p reporting <schema/mysql-migrations/v0.9.1.sql
+```