Merge pull request #91 from Icinga/add-docs

Add docs

README.md

@@ -1,12 +1,12 @@
 # Icinga Cube
 
-[![PHP Support](https://img.shields.io/badge/php-%3E%3D%207.0-777BB4?logo=PHP)](https://php.net/)
+[![PHP Support](https://img.shields.io/badge/php-%3E%3D%207.2-777BB4?logo=PHP)](https://php.net/)
 ![Build Status](https://github.com/icinga/icingaweb2-module-cube/workflows/PHP%20Tests/badge.svg?branch=master)
 [![Github Tag](https://img.shields.io/github/tag/Icinga/icingaweb2-module-cube.svg)](https://github.com/Icinga/icingaweb2-module-cube)
 
 ![Icinga Logo](https://icinga.com/wp-content/uploads/2014/06/icinga_logo.png)
 
-The Icinga Cube is a tiny but useful [Icinga Web 2](https://github.com/Icinga/icingaweb2)
+The Icinga Cube is a tiny but useful [Icinga Web](https://github.com/Icinga/icingaweb2)
 module. It currently shows host and service statistics (total count, health) grouped by
 various custom variables in multiple dimensions.
 
@@ -40,13 +40,12 @@ the Cube to fit your needs.
 
 ![Cube - Configure Dimensions](doc/img/cube_move-up.png)
 
-Want to drill down? Choose a slice and get your
- answers:
+Want to drill down? Choose a slice and get your answers:
 
 ![Cube - Configure Dimensions](doc/img/cube_slice.png)
 
 All facts configured for systems monitored by [Icinga](https://www.icinga.com/)
- can be used for your research.
+can be used for your research.
 
 For Icinga Director users
 -------------------------
@@ -59,40 +58,7 @@ modify multiple hosts at once.
 
 ![Cube - Director multi-edit](doc/img/cube_director.png)
 
-For Developers
---------------
-
-Our main intention when developing the Icinga Cube was too provide a modular small
-framework allowing you to drill into data provided from various sources. So it
-provides hooks for custom Cubes, related Renderers or just custom action links.
-
-For DBAs
---------
-
-Yes, it's mostly what the name suggests. Just a configurable rollup cube,
-providing a frontend allowing you to add and flip dimensions at will. You
-can slice and dice your data, drill down and pivot/rotate the whole cube.
-
-Requirements
-------------
-
-Icinga Web 2 v2.9 and the icinga-php-library v0.9.0.
-
-If you are using PostgreSQL, you need at least 9.5 which provides the `ROLLUP` feature.
-
 Installation
 ------------
 
-Install it [like any other module](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation).
-Use `cube` as name.
-
-Configuration
--------------
-
-Enable the module. That's it.
-
-Permissions
------------
-
-Someone able to access the cube will only see statistics for the objects they have permissions to view. Blacklist properties also apply.
-Restrictions applied to other modules will have no effect, at least not unless those modules provide their own Icinga Cube hooks taking care about such.
+To install Icinga Cube see [Installation](https://icinga.com/docs/icinga-cube/latest/doc/02-Installation/).

doc/01-About.md

@@ -0,0 +1,58 @@
+# Icinga Cube
+
+The Icinga Cube is a tiny but useful [Icinga Web](https://github.com/Icinga/icingaweb2)
+module. It currently shows host and service statistics (total count, health) grouped by
+various custom variables in multiple dimensions.
+
+![Cube - Overview](img/cube_simple.png)
+
+It will be your new best friend in case you are running a large environment and
+want to get a quick answers to questions like:
+
+* Which project uses how many servers per environment at which location/site?
+  * Who occupies most servers?
+  * How many of those are used in production?
+  * Which project has only development and test boxes? 
+* Which operating system is used for which project and in which environment?
+  * Do we still have Debian Lenny?
+  * Which projects are to blame for this?
+  * Do we have applications where the operating systems used differ in staging
+    and production? 
+* Which project uses which operating system version for which application?
+  * Which projects have homogeneous environments?
+  * Which projects are at a consistent patch level?
+  * How many RHEL 6 variants (6.1, 6.2, 6.3...) do we use?
+  * Who is running the oldest ones? In production?
+* Which projects are still using physical servers in which environment?
+
+For Businessmen - Drill and Slice
+---------------------------------
+
+Get answers to your questions. Quick and fully autonomous, using the cube
+requires no technical skills. Choose amongst all available dimensions and rotate
+the Cube to fit your needs.
+
+![Cube - Configure Dimensions](img/cube_move-up.png)
+
+Want to drill down? Choose a slice and get your answers:
+
+![Cube - Configure Dimensions](img/cube_slice.png)
+
+All facts configured for systems monitored by [Icinga](https://www.icinga.com/)
+can be used for your research.
+
+For Icinga Director users
+-------------------------
+
+![Cube - Action Links](img/cube_action-links.png)
+
+In case you are using the [Icinga Director](https://github.com/Icinga/icingaweb2-module-director),
+in addition to the multi-selection/edit feature the cube provides a nice way to
+modify multiple hosts at once.
+
+![Cube - Director multi-edit](img/cube_director.png)
+
+Installation
+------------
+
+To install Icinga Cube see [Installation](02-Installation.md).

doc/02-Installation.md

@@ -0,0 +1,235 @@
+<!-- {% if index %} -->
+# Installing Icinga Cube
+
+The recommended way to install Icinga Cube 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 Cube.
+
+<!-- {% else %} -->
+<!-- {% if not from_source %} -->
+## Adding Icinga Package Repository
+
+The recommended way to install Icinga Cube is to use prebuilt packages from our official release repository.
+
+!!! tip
+
+    If you install Icinga Cube on a node that has Icinga 2, Icinga DB or Icinga Web installed via packages,
+    proceed to [installing the Icinga Cube package](#installing-icinga-cube-package) as
+    the repository is already configured.
+
+Here's how to add the official release repository:
+
+<!-- {% if amazon_linux %} -->
+<!-- {% if not icingaDocs %} -->
+### Amazon Linux 2 Repository
+<!-- {% endif %} -->
+!!! info
+
+    A paid repository subscription is required for Amazon Linux 2 repositories. Get more information on
+    [icinga.com/subscription](https://icinga.com/subscription).
+
+    Don't forget to fill in the username and password section with appropriate credentials in the local .repo file.
+
+```bash
+rpm --import https://packages.icinga.com/icinga.key
+wget https://packages.icinga.com/subscription/amazon/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
+```
+<!-- {% endif %} -->
+
+<!-- {% if centos %} -->
+<!-- {% if not icingaDocs %} -->
+### CentOS Repository
+<!-- {% endif %} -->
+```bash
+rpm --import https://packages.icinga.com/icinga.key
+wget https://packages.icinga.com/centos/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
+```
+<!-- {% endif %} -->
+
+<!-- {% if debian %} -->
+<!-- {% if not icingaDocs %} -->
+### Debian Repository
+<!-- {% endif %} -->
+
+```bash
+apt-get update
+apt-get -y install apt-transport-https wget gnupg
+
+wget -O - https://packages.icinga.com/icinga.key | apt-key add -
+
+DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
+ echo "deb https://packages.icinga.com/debian icinga-${DIST} main" > \
+ /etc/apt/sources.list.d/${DIST}-icinga.list
+ echo "deb-src https://packages.icinga.com/debian icinga-${DIST} main" >> \
+ /etc/apt/sources.list.d/${DIST}-icinga.list
+
+apt-get update
+```
+<!-- {% endif %} -->
+
+<!-- {% if rhel %} -->
+<!-- {% if not icingaDocs %} -->
+### RHEL Repository
+<!-- {% endif %} -->
+!!! info
+
+    A paid repository subscription is required for RHEL repositories. Get more information on
+    [icinga.com/subscription](https://icinga.com/subscription).
+
+    Don't forget to fill in the username and password section with appropriate credentials in the local .repo file.
+
+```bash
+rpm --import https://packages.icinga.com/icinga.key
+wget https://packages.icinga.com/subscription/rhel/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
+```
+<!-- {% endif %} -->
+
+<!-- {% if sles %} -->
+<!-- {% if not icingaDocs %} -->
+### SLES Repository
+<!-- {% endif %} -->
+!!! info
+
+    A paid repository subscription is required for SLES repositories. Get more information on
+    [icinga.com/subscription](https://icinga.com/subscription).
+
+    Don't forget to fill in the username and password section with appropriate credentials in the local .repo file.
+
+```bash
+rpm --import https://packages.icinga.com/icinga.key
+
+zypper ar https://packages.icinga.com/subscription/sles/ICINGA-release.repo
+zypper ref
+```
+<!-- {% endif %} -->
+
+<!-- {% if ubuntu %} -->
+<!-- {% if not icingaDocs %} -->
+### Ubuntu Repository
+<!-- {% endif %} -->
+
+```bash
+apt-get update
+apt-get -y install apt-transport-https wget gnupg
+
+wget -O - https://packages.icinga.com/icinga.key | apt-key add -
+
+. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; \
+ echo "deb https://packages.icinga.com/ubuntu icinga-${DIST} main" > \
+ /etc/apt/sources.list.d/${DIST}-icinga.list
+ echo "deb-src https://packages.icinga.com/ubuntu icinga-${DIST} main" >> \
+ /etc/apt/sources.list.d/${DIST}-icinga.list
+
+apt-get update
+```
+<!-- {% endif %} -->
+
+## Installing Icinga Cube Package
+
+Use your distribution's package manager to install the `icinga-cube` package as follows:
+
+<!-- {% if amazon_linux %} -->
+<!-- {% if not icingaDocs %} -->
+#### Amazon Linux 2
+<!-- {% endif %} -->
+```bash
+yum install icinga-cube
+```
+<!-- {% endif %} -->
+
+<!-- {% if centos %} -->
+<!-- {% if not icingaDocs %} -->
+#### CentOS
+<!-- {% endif %} -->
+!!! info
+
+    Note that installing Icinga Cube is only supported on CentOS 7 as CentOS 8 is EOL.
+
+```bash
+yum install icinga-cube
+```
+<!-- {% endif %} -->
+
+<!-- {% if debian or ubuntu %} -->
+<!-- {% if not icingaDocs %} -->
+#### Debian / Ubuntu
+<!-- {% endif %} -->
+```bash
+apt-get install icinga-cube
+```
+<!-- {% endif %} -->
+
+<!-- {% if rhel %} -->
+#### RHEL 8 or Later
+
+```bash
+dnf install icinga-cube
+```
+
+#### RHEL 7
+
+```bash
+yum install icinga-cube
+```
+<!-- {% endif %} -->
+
+<!-- {% if sles %} -->
+<!-- {% if not icingaDocs %} -->
+#### SLES
+<!-- {% endif %} -->
+```bash
+zypper install icinga-cube
+```
+<!-- {% endif %} -->
+
+<!-- {% else %} --><!-- {# end if not from_source #} -->
+<!-- {% if not icingaDocs %} -->
+## Installing Icinga Cube from Source
+<!-- {% endif %} -->
+
+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 `cube` as the module name. The following requirements must also be met.
+
+### Requirements
+
+* PHP (≥7.2)
+* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.9)
+* [Icinga DB Web](https://github.com/Icinga/icingadb-web) (≥1.0)
+* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.9)
+
+If you are using PostgreSQL, you need at least 9.5 which provides the `ROLLUP` feature.
+<!-- {% endif %} --><!-- {# end else if not from_source #} -->
+
+## Configuring Icinga Cube
+
+<!-- {% if not from_source %} -->
+The Icinga Web PHP framework is required to configure and run the Icinga Cube.
+Package installations of `icinga-cube` already set up the necessary dependencies.
+
+If Icinga Web has not been installed or set up before,
+you have completed the instructions here and can proceed to
+<!-- {% if amazon_linux %} -->
+[install the web server on Amazon Linux](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/06-Amazon-Linux/#install-the-web-server),
+<!-- {% endif %} -->
+<!-- {% if centos %} -->
+[install the web server on CentOS](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/03-CentOS/#install-the-web-server),
+<!-- {% endif %} -->
+<!-- {% if debian %} -->
+[install the web server on Debian](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/01-Debian/#install-the-web-server),
+<!-- {% endif %} -->
+<!-- {% if rhel %} -->
+[install the web server on RHEL](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/04-RHEL/#install-the-web-server),
+<!-- {% endif %} -->
+<!-- {% if sles %} -->
+[install the web server on SLES](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/05-SLES/#install-the-web-server),
+<!-- {% endif %} -->
+<!-- {% if ubuntu %} -->
+[install the web server on Ubuntu](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/02-Ubuntu/#install-the-web-server),
+<!-- {% endif %} -->
+which will then take you to the web-based setup wizard, which also allows you to enable the Icinga Cube.
+<!-- {% endif %} --><!-- {# end if not from_source #} -->
+
+For Icinga Web setups already running, log in to Icinga Web with a privileged user and enable the Icinga Cube.
+<!-- {% endif %} --><!-- {# end else if index #} -->

doc/02-Installation.md.d/01-Amazon-Linux.md

@@ -0,0 +1,3 @@
+# Installing Icinga Cube on Amazon Linux
+<!-- {% set amazon_linux = True %} -->
+<!-- {% include "02-Installation.md" %} -->

doc/02-Installation.md.d/02-CentOS.md

@@ -0,0 +1,3 @@
+# Installing Icinga Cube on CentOS
+<!-- {% set centos = True %} -->
+<!-- {% include "02-Installation.md" %} -->

doc/02-Installation.md.d/03-Debian.md

@@ -0,0 +1,3 @@
+# Installing Icinga Cube on Debian
+<!-- {% set debian = True %} -->
+<!-- {% include "02-Installation.md" %} -->

doc/02-Installation.md.d/04-RHEL.md

@@ -0,0 +1,3 @@
+# Installing Icinga Cube on RHEL
+<!-- {% set rhel = True %} -->
+<!-- {% include "02-Installation.md" %} -->

doc/02-Installation.md.d/05-SLES.md

@@ -0,0 +1,3 @@
+# Installing Icinga Cube on SLES
+<!-- {% set sles = True %} -->
+<!-- {% include "02-Installation.md" %} -->

doc/02-Installation.md.d/06-Ubuntu.md

@@ -0,0 +1,3 @@
+# Installing Icinga Cube on Ubuntu
+<!-- {% set ubuntu = True %} -->
+<!-- {% include "02-Installation.md" %} -->

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

@@ -0,0 +1,3 @@
+# Installing Icinga Cube from Source
+<!-- {% set from_source = True %} -->
+<!-- {% include "02-Installation.md" %} -->