Merge pull request #4348 from Icinga/feature/add-basic-module-documentation

Add basic module documentation

doc/01-About.md

@@ -3,19 +3,6 @@
 Icinga Web 2 is a powerful PHP framework for web applications that comes in a clean and reduced design.
 It's fast, responsive, accessible and easily extensible with modules.
 
-## The monitoring module <a id="about-monitoring"></a>
-
-This is the core module for most Icinga Web 2 users.
-
-It provides an intuitive user interface for monitoring with Icinga 2.
-Especially there are lots of list and detail views (e.g. for hosts and services)
-you can sort and filter depending on what you want to see.
-
-You can also control the monitoring process itself by sending external commands to Icinga.
-Most such actions (like rescheduling a check) can be done with just a single click.
-
-More details about this module can be found in [this chapter](../modules/monitoring/doc/01-About.md#monitoring-module-about).
-
 ## Installation <a id="about-installation"></a>
 
 Icinga Web 2 can be installed easily from packages from the official package repositories.
@@ -55,7 +42,33 @@ They can be stored either in a database or in .ini files.
 See [here](07-Preferences.md#preferences) for more information about a user's preferences
 and how to configure their storage type.
 
-## Documentation <a id="about-documentation"></a>
+## Modules
+
+Modules extend Icinga Web 2 with additional functionality. They allow the integration of
+capabilities into existing views and even other modules. Be it a graph provider such as
+[Graphite](https://github.com/Icinga/icingaweb2-module-graphite) or a UI for the Icinga 2
+configuration like the [Director](https://github.com/Icinga/icingaweb2-module-director).
+
+See [here](08-Modules.md#modules) for information on how to install and configure modules.
+
+### The monitoring module <a id="about-monitoring"></a>
+
+> **Note for Icinga DB Users**
+>
+> This module is only for the IDO backend. Use [Icinga DB Web](https://github.com/Icinga/icingadb-web) instead.
+
+This is the core module for most Icinga Web 2 users.
+
+It provides an intuitive user interface for monitoring with Icinga 2.
+There are lots of list and detail views (e.g. for hosts and services)
+you can sort and filter depending on what you want to see.
+
+You can also control the monitoring process itself by sending external commands to Icinga.
+Most such actions (like rescheduling a check) can be done with just a single click in the UI.
+
+More details about this module can be found in [this chapter](../modules/monitoring/doc/01-About.md#monitoring-module-about).
+
+### Documentation <a id="about-documentation"></a>
 
 With the documentation module you can read the documentation of the framework (and any module) directly in the user interface.
 
@@ -63,7 +76,7 @@ The module can also export the documentation to PDF.
 
 More details about this module can be found in [this chapter](../modules/doc/doc/01-About.md#doc-module-about).
 
-## Translation <a id="about-translation"></a>
+### Translation <a id="about-translation"></a>
 
 Icinga Web 2 and all modules by Icinga utilize gettext to provide translations into other languages from the default
 English (en_US). However, the actual language specific files (locales) are not separately included in every project.

doc/08-Modules.md

@@ -0,0 +1,69 @@
+# Modules
+
+## Installation
+
+A module should be installed in one of the [configured module paths](03-Configuration.md#general-configuration).
+The default path in most installations is `/usr/share/icingaweb2/modules`.
+
+Each directory in there contains the files for a particular module. The directory's name has to be the one
+that is provided by the module's documentation. If there is none provided, it is usually the name of the
+module in all lowercase. Some modules may use a name prefixed with `icingaweb2-module-`. If this is the case,
+the directory's name should be that, but without the prefix.
+(e.g. `icingaweb2-module-map` turns into `/usr/share/icingaweb2/modules/map`)
+
+> **Note:**
+>
+> Remember to ensure that your web-server can access those files. Though, read permission only.
+
+Once a module's files are in place, it needs to be enabled first before it can be used. This can either be done in
+the UI at `Configuration -> Modules` or by using the icingacli: `icingacli module enable map`
+
+In order for other non-admin users to access the module's functionality, it is required to permit access first.
+This is done by granting the permission `module/<module-name>`. (e.g. `module/map`)
+
+### Module Specific Instructions
+
+A module may require further installation steps. Whether these need to be performed before enabling the module,
+should be provided by the module's documentation. In any case, don't forget to apply these as well, otherwise
+the module will most likely not function correctly.
+
+### Examples
+
+There are sample installation instructions provided for your convenience:
+
+**Sample Tarball installation**
+
+```sh
+MODULE_NAME="map"
+MODULE_VERSION="v1.1.0"
+MODULE_AUTHOR="nbuchwitz"
+MODULES_PATH="/usr/share/icingaweb2/modules"
+MODULE_PATH="${MODULES_PATH}/${MODULE_NAME}"
+RELEASES="https://github.com/${MODULE_AUTHOR}/icingaweb2-module-${MODULE_NAME}/archive"
+mkdir "$MODULE_PATH" \
+&& wget -q $RELEASES/${MODULE_VERSION}.tar.gz -O - \
+   | tar xfz - -C "$MODULE_PATH" --strip-components 1
+icingacli module enable "${MODULE_NAME}"
+```
+
+**Sample GIT installation**
+
+```sh
+MODULE_NAME="map"
+MODULE_VERSION="v1.1.0"
+MODULE_AUTHOR="nbuchwitz"
+REPO="https://github.com/${MODULE_AUTHOR}/icingaweb2-module-${MODULE_NAME}"
+MODULES_PATH="/usr/share/icingaweb2/modules"
+git clone ${REPO} "${MODULES_PATH}/${MODULE_NAME}" --branch "${MODULE_VERSION}"
+icingacli module enable "${MODULE_NAME}"
+```
+
+## Configuration
+
+A module may also require configuration. Most modules provide additional tabs at their configuration page.
+This is accessible in the UI at `Configuration -> Modules`. If not, and something isn't working, check the
+module's documentation again for hints.
+
+If you need access to a module's configuration files directly, they should be in a subdirectory `modules`
+of Icinga Web 2's configuration directory. That is usually `/etc/icingaweb2/modules`. Each directory in
+there should be named the same as its installation path. (e.g. `/etc/icingaweb2/modules/map`)