doc: re-structure, more documentation

fixes #11093

README.md

@@ -12,44 +12,11 @@ of them at once.
 
 ![Icinga Director](https://www.icinga.org/wp-content/uploads/2016/02/director_main_screen.png)
 
-Requirements
-------------
+Learn more about the Director in the documentation:
 
-* Icinga 2 (>= 2.4.3)
-* Icinga Web 2 (>= 2.2.0)
-* A database, MySQL (>= 5.1) or PostgreSQL (>= 9.1) database (MariaDB and other forks are also fine)
-* php5-curl
-
-Installation
-------------
-
-### Create Icinga Director database
-
-#### MySQL
-
-    mysql -e "CREATE DATABASE director CHARACTER SET 'utf8';
-       GRANT ALL ON director.* TO director@localhost IDENTIFIED BY 'some-password';"
-
-#### PostgreSQL
-
-    CREATE DATABASE director WITH ENCODING 'UTF8';
-    CREATE USER director WITH PASSWORD 'some-password';
-    GRANT ALL PRIVILEGES ON DATABASE director TO director;
-
-
-Configure Icinga Web 2
-----------------------
-
-As with any Icinga Web 2 module, installation is pretty straight-forward. In
-case you're installing it from source all you have to do is to drop the director
-module in one of your module paths. Then go to your web frontend, Configuration,
-Modules, director - and enable the module. 
-
-In your web frontend please go to System / Configuration / Resources and create
-a new database resource pointing to your newly created database. Last but not
-least you have to tell the director module to use this newly created database
-resource.
-
-In case you prefer automated or manual installation please learn more about
-[automated installations](doc/30-Automation.md) in the related [section](doc/30-Automation.md) of our documentation.
+* [Introduction](doc/01-Introduction.md)
+* [Installation](doc/02-Installation.md)
+* [Automation](doc/03-Automation.md)
+* [Getting started](doc/04-Getting-started.md) 
+* [REST API](doc/70-REST-API.md) 
 

doc/02-Installation.md

@@ -0,0 +1,51 @@
+Installation
+============
+
+These are the instructions for manual Director installations. You can
+learn moree about how to automate this in the [automation](03-Automation.md) section
+of this documentation.
+
+Requirements
+------------
+
+* Icinga 2 (>= 2.4.3)
+* Icinga Web 2 (>= 2.2.0)
+* A database, MySQL (>= 5.1) or PostgreSQL (>= 9.1) database (MariaDB and
+  other forks are also fine)
+* php5-curl
+
+Database
+--------
+
+### Create an empty Icinga Director database
+
+#### MySQL
+
+    mysql -e "CREATE DATABASE director CHARACTER SET 'utf8';
+       GRANT ALL ON director.* TO director@localhost IDENTIFIED BY 'some-password';"
+
+#### PostgreSQL
+
+
+    psql -q -c "CREATE DATABASE director WITH ENCODING 'UTF8';"
+    psql director -q -c "CREATE USER director WITH PASSWORD 'some-password';
+    GRANT ALL PRIVILEGES ON DATABASE director TO director;"
+
+
+Configure Icinga Web 2
+----------------------
+
+In your web frontend please go to System / Configuration / Resources and create
+a new database resource pointing to your newly created database. Please make
+sure that you choose `utf8` as an encoding.
+
+As with any Icinga Web 2 module, installation is pretty straight-forward. In
+case you're installing it from source all you have to do is to drop the director
+module in one of your module paths. You can examine (and set) the module path(s)
+in `Configuration / General`. In a tipical environment you'll probably drop the
+module to `/usr/share/icingaweb2/modules/director`. Please note that the directory
+name MUST be `director` and not `icingaweb2-module-director` or anything else.
+
+Now go to your web frontend, Configuration, Modules, director - and enable the
+module. Last but not least you have to tell the director module to use this newly
+created database resource.

doc/04-Getting-started.md

@@ -0,0 +1,25 @@
+Preparing your Icinga 2 environment for the Director
+====================================================
+
+Create an API user
+------------------
+
+```icinga2
+object ApiUser "director" {
+  password = "***"
+  permissions = [ "*" ]
+  //client_cn = ""
+}
+```
+
+Start with a new, empty Icinga setup. Director is not allowed to modify
+existing configuration in `/etc/icinga2`, and while importing existing
+config is possible (happens for examply automacigally at kickstart time)
+this is an advanced task you should not tackle at the early beginning.
+
+Take some time to really understand work with Icinga Director first.
+
+Working with Agents and Config Zones
+====================================
+
+Hint: Large: max packet size

doc/70-REST-API.md

@@ -37,7 +37,7 @@ provided property. However, you must always be ready to accept new properties.
 URL scheme and supported methods
 --------------------------------
 
-We support GET, POST, PUT and DELETE. 
+We support GET, POST, PUT and DELETE.
 
 | Method | Meaning
 | ------ | ------------------------------------------------------------
@@ -394,7 +394,7 @@ If merging properties is not what you want, `PUT` comes to the rescue:
     PUT director/host?name=apitest
 
 ```
-{ "vars": { "event": [ "Icinga", "Camp" ] } 
+{ "vars": { "event": [ "Icinga", "Camp" ] }
 ```
 
 All other properties vanished, all but name and type: