1<a id="Installation"></a>Installation
2=====================================
3
4These are the instructions for manual Director installations. You can
5learn more about how to automate this in the [automation](03-Automation.md) section
6of this documentation. In case you already installed Director and want to upgrade
7to the latest version, please [read on here](05-Upgrading.md).
8
9Requirements
10------------
11
12* Icinga 2 (&gt;= 2.6.0)
13  * It is recommended to use the latest feature release of Icinga 2
14  * All versions since 2.4.3 should also work fine, but
15    we do no longer test and support them.
16  * Some features require newer Icinga 2 releases
17    * Flapping requires 2.8 for the thresholds to work - and at least 2.7 on all
18      nodes
19* Icinga Web 2 (&gt;= 2.6.0). All versions since 2.2 should also work fine, but
20  might show smaller UI bugs and are not actively tested
21* A database, MySQL (&gt;= 5.1) or PostgreSQL (&gt;= 9.1). MariaDB and other
22  MySQL forks are also fine. Mentioned versions are the required minimum,
23  for MySQL we suggest using at least 5.5.3, for PostgreSQL 9.4.
24* PHP (>= 5.4). For best performance please consider use 7.x
25* php-curl
26
27Database
28--------
29
30### Create an empty Icinga Director database
31
32HINT: You should replace `some-password` with a secure custom password.
33
34#### MySQL (or MariaDB)
35
36    mysql -e "CREATE DATABASE director CHARACTER SET 'utf8';
37       GRANT ALL ON director.* TO director@localhost IDENTIFIED BY 'some-password';"
38
39In case your MySQL root user is password-protected, please add `-p` to this
40command.
41
42#### PostgreSQL
43
44
45    psql -q -c "CREATE DATABASE director WITH ENCODING 'UTF8';"
46    psql director -q -c "CREATE USER director WITH PASSWORD 'some-password';
47    GRANT ALL PRIVILEGES ON DATABASE director TO director;
48    CREATE EXTENSION pgcrypto;"
49
50Hint: pgcrypto helps to boost performance, but is currently optional. In case you
51do not have it available on your platform and/or do not know how to solve this
52just leave away the 'CREATE EXTENSION' part.
53
54Web-based Configuration
55-----------------------
56
57The following steps should guide you through the web-based Kickstart wizard.
58In case you prefer automated configuration, you should check the dedicated
59[documentation section](03-Automation.md).
60
61### Create a Database resource
62
63In your web frontend please go to `Configuration / Application / Resources`
64and create a new database resource pointing to your newly created database.
65Please make sure that you choose `utf8` as an encoding.
66
67
68### Install the Director module
69
70As with any Icinga Web 2 module, installation is pretty straight-forward. In
71case you're installing it from source all you have to do is to drop the director
72module in one of your module paths. You can examine (and set) the module path(s)
73in `Configuration / Application`. In a typical environment you'll probably drop the
74module to `/usr/share/icingaweb2/modules/director`. Please note that the directory
75name MUST be `director` and not `icingaweb2-module-director` or anything else.
76
77#### Installation from release tarball
78
79Download the [latest version](https://github.com/Icinga/icingaweb2-module-director/releases)
80and extract it to a folder named `director` in one of your Icinga Web 2 module path directories.
81
82You might want to use a script as follows for this task:
83
84    ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
85    REPO_URL="https://github.com/icinga/icingaweb2-module-director"
86    TARGET_DIR="${ICINGAWEB_MODULEPATH}/director"
87    MODULE_VERSION="1.6.2"
88    URL="${REPO_URL}/archive/v${MODULE_VERSION}.tar.gz"
89    install -d -m 0755 "${TARGET_DIR}"
90    wget -q -O - "$URL" | tar xfz - -C "${TARGET_DIR}" --strip-components 1
91
92Proceed to enabling the module.
93
94#### Installation from GIT repository
95
96Another convenient method is the installation directly from our GIT repository.
97Just clone the repository to one of your Icinga Web 2 module path directories.
98It will be immediately ready for use:
99
100
101    ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
102    REPO_URL="https://github.com/icinga/icingaweb2-module-director"
103    TARGET_DIR="${ICINGAWEB_MODULEPATH}/director"
104    MODULE_VERSION="1.6.2"
105    git clone "${REPO_URL}" "${TARGET_DIR}" --branch v${MODULE_VERSION}
106
107You can now directly use our current GIT master or check out a specific version.
108
109    cd "${TARGET_DIR}" && git checkout "v${MODULE_VERSION}"
110
111Proceed to enabling the module.
112
113#### Enable the newly installed module
114
115Enable the `director` module either on the CLI by running
116
117    icingacli module enable director
118
119Or go to your Icinga Web 2 frontend, choose `Configuration / Modules`,
120select the `director` module and choose `State: enable`.
121
122### Run the graphical kickstart wizard
123
124Choose either `Icinga Director` directly from the main menu or
125navigate into `Configuration / Modules / director` and select the `Configuration`
126tab.
127
128Either way you'll reach the kickstart wizards. Follow the instructions and
129you're all done!
130
131