2 files changed, 158 insertions, 0 deletions
diff --git a/doc/02-Installation.md b/doc/02-Installation.md
new file mode 100644
index 0000000..10604d1
--- /dev/null
+++ b/doc/02-Installation.md
@@ -0,0 +1,75 @@
+<!-- {% if index %} -->
+# Installing Icinga Director
+
+The recommended way to install Icinga Director 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 to run Icinga Director
+and if it is not already set up, it is best to do this first.
+
+The following steps will guide you through installing and setting up Icinga Director.
+
+To upgrade an existing Icinga Director installation to a newer version,
+see the [upgrading](05-Upgrading.md) documentation for the necessary steps.
+
+If you want to automate the installation, configuration and upgrade,
+you can learn more about it in the [automation](03-Automation.md) section of this documentation.
+
+## Optional Requirements
+
+The following requirements are not necessary for installation,
+but may be needed later if you want to import from one of the listed sources:
+
+* For **IBM Db2** imports: `php-pdo-ibm`
+* For **Microsoft SQL Server** imports: `php-mssql`, `php-pdo-dblib` or `php-sybase` depending on your platform
+* For **Oracle Database** imports: `php-oci8` or `php-pdo-oci` depending on your platform
+* For **SQLite** imports: `php-pdo-sqlite`
+<!-- {% else %} -->
+<!-- {% if not icingaDocs %} -->
+
+## Installing Icinga Director Package
+
+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-director` package
+or install [from source](02-Installation.md.d/From-Source.md).
+<!-- {% endif %} -->
+
+## Setting up the Database
+
+A MySQL (≥5.7), MariaDB (≥10.1), or PostgreSQL (≥9.6) database is required to run Icinga Director.
+Please follow the steps listed for your target database, to set up the database and the user.
+The schema will be imported later via the web interface.
+
+### Setting up a MySQL or MariaDB Database
+
+> **Warning**
+> Make sure to replace `CHANGEME` with a secure password.
+
+```
+mysql -e "CREATE DATABASE director CHARACTER SET 'utf8';
+  CREATE USER director@localhost IDENTIFIED BY 'CHANGEME';
+  GRANT ALL ON director.* TO director@localhost;"
+```
+
+### Setting up a PostgreSQL Database
+
+> **Warning**
+> Make sure to replace `CHANGEME` with a secure password.
+
+```
+psql -q -c "CREATE DATABASE director WITH ENCODING 'UTF8';"
+psql director -q -c "CREATE USER director WITH PASSWORD 'CHANGEME';
+GRANT ALL PRIVILEGES ON DATABASE director TO director;
+CREATE EXTENSION pgcrypto;"
+```
+
+## Configuring Icinga Director
+
+Log in to your running Icinga Web setup with a privileged user
+and follow the steps below to configure Icinga Director:
+
+1. Create a new resource for the Icinga Director [database](#setting-up-the-database) via the
+   `Configuration → Application → Resources` menu.
+   Please make sure that you configure `utf8` as encoding.
+2. Select  `Icinga Director` directly from the main menu
+   and you will be taken to the kickstart wizard. Follow the instructions and you are done!
+<!-- {% 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
new file mode 100644
index 0000000..ea17233
--- /dev/null
+++ b/doc/02-Installation.md.d/From-Source.md
@@ -0,0 +1,83 @@
+# Installing Icinga Director from Source
+
+These are the instructions for manual Director installations.
+
+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 `director` as the module name. The following requirements must also be met.
+
+## Requirements
+
+* PHP (≥7.3)
+    * Director v1.10 is the last version with support for PHP v5.6
+* [Icinga 2](https://github.com/Icinga/icinga2) (≥2.8.0)
+    * It is recommended to use the latest feature release of Icinga 2
+    * All versions since 2.4.3 should also work fine, but
+      we do no longer test and support them.
+    * Some features require newer Icinga 2 releases
+        * Flapping requires 2.8 for the thresholds to work - and at least 2.7 on all
+          nodes
+* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.8.0). All versions since 2.2 should also work fine, but
+  might show smaller UI bugs and are not actively tested
+* The following Icinga modules must be installed and enabled:
+    * [incubator](https://github.com/Icinga/icingaweb2-module-incubator) (≥0.18.0)
+    * If you are using Icinga Web <2.9.0, the following modules are also required
+        * [ipl](https://github.com/Icinga/icingaweb2-module-ipl) (≥0.5.0)
+        * [reactbundle](https://github.com/Icinga/icingaweb2-module-reactbundle) (≥0.9.0)
+* A database: MariaDB (≥10.1), MySQL (≥5.7), PostgreSQL (≥9.6). Other
+  forks and older versions might work, but are neither tested nor supported
+* `php-pdo-mysql` and/or `php-pdo-pgsql`
+* `php-curl`
+* `php-iconv`
+* `php-pcntl` (might already be built into your PHP binary)
+* `php-posix` or `php-process` depending on your platform
+* `php-sockets` (might already be built into your PHP binary)
+
+## Installing from Release Tarball
+
+Download the [latest version](https://github.com/Icinga/icingaweb2-module-director/releases)
+and extract it to a folder named `director` in one of your Icinga Web module path directories.
+
+You might want to use a script as follows for this task:
+
+```shell
+MODULE_VERSION="1.10.2"
+ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
+REPO_URL="https://github.com/icinga/icingaweb2-module-director"
+TARGET_DIR="${ICINGAWEB_MODULEPATH}/director"
+URL="${REPO_URL}/archive/v${MODULE_VERSION}.tar.gz"
+
+install -d -m 0755 "${TARGET_DIR}"
+wget -q -O - "$URL" | tar xfz - -C "${TARGET_DIR}" --strip-components 1
+icingacli module enable director
+```
+
+## Installing from Git Repository
+
+Another convenient method is to install directly from our Git repository.
+Simply clone the repository in one of your Icinga web module path directories.
+
+You might want to use a script as follows for this task:
+
+```shell
+MODULE_VERSION="1.10.2"
+ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
+REPO_URL="https://github.com/icinga/icingaweb2-module-director"
+TARGET_DIR="${ICINGAWEB_MODULEPATH}/director"
+
+git clone "${REPO_URL}" "${TARGET_DIR}" --branch v${MODULE_VERSION}
+icingacli module enable director
+```
+
+## Setting up the Director Daemon
+
+For manual installations, the daemon user, its directory, and the systemd service need to be set up:
+
+```shell
+useradd -r -g icingaweb2 -d /var/lib/icingadirector -s /sbin/nologin icingadirector
+install -d -o icingadirector -g icingaweb2 -m 0750 /var/lib/icingadirector
+install -pm 0644 contrib/systemd/icinga-director.service /etc/systemd/system
+systemctl daemon-reload
+systemctl enable --now icinga-director
+```
+<!-- {% include "02-Installation.md" %} -->