Resolve "[Orchestrator] - Installation and configuration manual"

source/fusiondirectory-orchestrator/configuration/configuration.rst

+Configuration
+-------------
+
+| Orchestrator requires a one file to be configured properly.
+
+Configuration file
+""""""""""""""""""
+.. note::
+	The editable file is located at **/etc/fusiondirectory-orchestrator/orchestrator.conf**
+
+[LDAP settings]
+^^^^^^^^^^^^^^^
+.. code-block:: shell
+	
+  LDAP_HOST="localhost"
+
+Required in order to connect to the proper host.
+FQDN or IP must be provided.
+
+.. code-block:: shell
+	
+  LDAP_ADMIN="cn=admin,dc=fusiondirectory,dc=org"
+
+Required by LDAP in order to use the proper privileges.
+
+.. code-block:: shell
+	
+  LDAP_PWD="ldap_pwd"
+
+Required password to authenticate LDAP
+
+.. code-block:: shell
+	
+  LDAP_OU_USER="ou=people,dc=fusiondirectory"
+
+Required to ease the research of the branch people by endpoints.
+
+[JWT token settings]
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: shell
+	
+  #SECRET_KEY can be generated via a 256 bit Wep key generator such as 
+	#https://allkeysgenerator.com/
+	SECRET_KEY="256 bit key"
+
+Required to secure and validate the generation of access and refresh tokens.
+
+[SMTP server settings]
+^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: shell
+	
+  MAIL_USER="mail_user"
+
+The login ID to authenticate to the specified SMTP server.
+
+.. code-block:: shell
+	
+  MAIL_PASS="mail_pwd"
+
+The password used for above authentication.
+
+.. code-block:: shell
+	
+  MAIL_HOST="fqdn or IP"
+
+The SMTP server domain name or IP.
+
+.. code-block:: shell
+	
+  MAIL_SEC="ssl"
+
+The required secure methode. "TLS" can be used for "STARTLS".
+Please note the importance of lowercase in 'ssl' or 'tls'.
+
+.. code-block:: shell
+	
+  MAIL_PORT="SMTP port number"
+
+The TCP/UDP port number of the SMTP server.(Example: SSL 465 / TLS 586).
+
+.. Note::
+
+  | Orchestrator is highly depending on the URL rewriting mechanism of the web server.
+  | In case of Apache2 ".htaccess" files are responsible for that logic.
+
+  | Although informative, there should not be any value of modifying the contents of those files.
+  | The goal is to redirect any call on URI to the main index file located in API directory. 

source/fusiondirectory-orchestrator/endpoints/index.rst

+FusionDirectory Orchestrator Endpoints
+======================================
+
+
+.. toctree::
+   :maxdepth: 2
+
+   tasks/index.rst

source/fusiondirectory-orchestrator/endpoints/tasks/description.rst

+Description
+===========
+
+Tasks is an endpoints of Orchestrator.
+
+.. note::
+  It is reachable via **https://your_fqdn/api/tasks/**
+
+Arguments
+---------
+
+- Mail 
+
+You can :
+ - Retrieve all tasks of type mail.
+ - Process all tasks of type mail and forward the related e-mails.

source/fusiondirectory-orchestrator/endpoints/tasks/functionalities.rst

+
+Functionalities
+===============
+
+| E-mails are being sent based on the schedule of the processed task.
+
+How it works
+------------
+
+Asking the proper endpoints with the allowed HTTP methods will trigger the required action.
+
+Examples
+--------
+
+.. note::
+
+  | An orchestrator client is being developped in order to automate some of the below examples.
+  | It will allow easier management of repeated tasks within a CRON job.
+
+
+Get access-token
+""""""""""""""""
+
+.. code-block:: shell
+
+   # Login and get access-token
+   curl -X POST -H "Content-Type: application/json" https://example.org/orchestrator/api/login -d '{"username":"admin","password":"secret"}'
+
+Get all mail tasks
+""""""""""""""""""
+
+.. code-block:: shell
+
+   # Get all mail tasks using the access-token
+   curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {token}"  https://example.org/orchestrator/api/tasks/mail
+
+Send e-mails
+""""""""""""
+
+.. code-block:: shell
+
+   # Login and get access-token
+   curl -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer {token}"  https://example.org/orchestrator/api/tasks/mail
+
+Refresh access token
+""""""""""""""""""""
+
+.. code-block:: shell
+
+    # Refresh access token with refresh token
+    curl -X POST -H "Content-Type: application/json" http://192.168.1.100:8080/orchestrator/api/refresh -d '{"token":"refresh-token"}'
+
+Conditions
+----------
+
+In order to process mail tasks, a few conditions are analysed:
+
+- Schedule for the tasks.
+- A max-emails threshold to be sent.
+- A time interval between mail tasks processing.
+
+.. note::
+   The settings for above conditions are found within FusionDirectory configuration menu.

source/fusiondirectory-orchestrator/endpoints/tasks/index.rst

+Orchestrator Mail Task
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   description.rst
+   functionalities.rst

source/fusiondirectory-orchestrator/index.rst

+FusionDirectory Orchestrator
+============================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   whatis/orchestrator.rst
+   prerequisite/prerequisite.rst
+   install/index.rst
+   configuration/configuration.rst
+   endpoints/index.rst
+   license/index.rst

source/fusiondirectory-orchestrator/install/centos/centos-orchestrator-install.rst

+Installing Dependencies
+'''''''''''''''''''''''
+
+All The needed dependancies are resolved by the centos packages
+
+.. note::
+
+   The repositories are in https for Centos, same repos as FusionDirectory.
+
+Install FusionDirectory Orchestrator 
+''''''''''''''''''''''''''''''''''''
+
+You can then install Orchestrator by running: 
+
+.. code-block:: shell
+
+   yum install fusiondirectory-orchestrator
+   yum install fusiondirectory-orchestrator-schema
+
+FusionDirectory Orchestrator Schema installation
+''''''''''''''''''''''''''''''''''''''''''''''''
+
+Now that we have Orchestrator installed, we need to install the
+Orchestrator schemas into our LDAP database.
+
+We can easily do this by running:
+
+.. code-block:: shell
+
+   fusiondirectory-schema-manager --insert-schema /etc/openldap/schema/fusiondirectory/fusiondirectory-orchestrator.schema
+
+You should now be able to use Orchestrator API by visiting :
+
+http://SERVER-IP/orchestrator/api
+
+
+

source/fusiondirectory-orchestrator/install/centos/index.rst

+Install FusionDirectory Orchestrator on Centos
+==============================================
+
+.. toctree::
+   :maxdepth: 4
+
+   centos-orchestrator-install.rst

source/fusiondirectory-orchestrator/install/debian/debian-orchestrator-install.rst

+Installing Dependencies
+'''''''''''''''''''''''
+
+All The needed dependancies are resolved by the debian packages
+
+.. note::
+
+   The repositories are in https for Debian
+   so you will need to install **apt-transport-https**
+
+Install FusionDirectory Orchestrator 
+''''''''''''''''''''''''''''''''''''
+
+You can then install Orchestrator by running: 
+
+.. code-block:: shell
+
+   apt-get install fusiondirectory-orchestrator
+   apt-get install fusiondirectory-orchestrator-schema
+
+FusionDirectory Orchestrator Schema installation
+''''''''''''''''''''''''''''''''''''''''''''''''
+
+Now that we have Orchestrator installed, we need to install the
+Orchestrator schemas into our LDAP database.
+
+We can easily do this by running:
+
+.. code-block:: shell
+
+   fusiondirectory-schema-manager --insert-schema /etc/ldap/schema/fusiondirectory/fusiondirectory-orchestrator.schema
+
+You should now be able to use Orchestrator API by visiting :
+
+http://SERVER-IP/orchestrator/api
+
+
+

source/fusiondirectory-orchestrator/install/debian/index.rst

+Install FusionDirectory Orchestrator on Debian
+==============================================
+
+.. toctree::
+   :maxdepth: 4
+
+   debian-orchestrator-install.rst

source/fusiondirectory-orchestrator/install/index.rst

+Install FusionDirectory Orchestrator 
+====================================
+
+.. toctree::
+   :maxdepth: 2
+
+   ../../gpg/index.rst
+   ../../repositories/index.rst
+   debian/index.rst
+   centos/index.rst

source/fusiondirectory-orchestrator/license/index.rst

+License
+=======
+
+.. toctree::
+   :maxdepth: 2
+
+   license

source/fusiondirectory-orchestrator/license/license.rst

+License
+=======
+
+FusionDirectory is available under the `GNU General Public License 2.0 <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_
+
+FusionDirectory documentation is under the `Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) <https://creativecommons.org/licenses/by-sa/4.0/>`_

source/fusiondirectory-orchestrator/prerequisite/prerequisite.rst

+Prerequisites
+=============
+
+FusionDirectory Orchestrator is a Web application that will need:
+
+* A webserver;
+* PHP;
+* An ldap server;
+* Fusion Directory 1.4 with configured tasks.
+
+Web server
+----------
+
+FusionDirectory Orchestrator requires the following web server that supports PHP and URL Rewriting:
+
+* `Apache 2 (or more recent) <http://httpd.apache.org>`_;
+
+PHP
+---
+
+As of 1.4 release, FusionDirectory Orchestrator requires `PHP <https://www.php.net>`_ 7.3 or 7.4.
+
+^^^^^^^^^^^^^^^^^^^^
+
+LDAP server
+-----------
+
+FusionDirectory Orchestrator will use the LDAP server managed by your FusionDirectory.
+
+Servers know to work are :
+
+* `OpenLDAP`_
+
+.. _OpenLDAP : https://www.openldap.org/

source/fusiondirectory-orchestrator/whatis/orchestrator.rst

+What is FusionDirectory Orchestrator ?
+======================================
+
+| FusionDirectory Orchestrator provides a web service solution serving a REST API.
+| It allows a granular management of some specialized tasks.
+
+Features
+^^^^^^^^
+
+- Tasks management.
+- Tasks execution.
+- JWT Authentication methods
+
+
+Tasks management
+^^^^^^^^^^^^^^^^
+
+| FusionDirectory Orchestrator REST API allows the retrieval of existing created Tasks.  
+| Offering a simple view on the status of each tasks. 
+
+It is possible to retrieve specialized tasks such as Mail. 
+
+Tasks execution
+^^^^^^^^^^^^^^^
+
+| One of the main aspect of FusionDirectory Orchestrator is to allow processing of some desired tasks.
+| In case of a task of type mail, the list of related emails will be sent if scheduled is matched.
+
+JWT authentication
+^^^^^^^^^^^^^^^^^^
+
+| It was decided to enhance our authentication mechanism and use the JWT methodology.
+| Allowing after proper username/password authentication the reception of an access and refresh token.
+
+The access token is to be used for any operations on FusionDirectory Orchestrator endpoints. 
+
+

source/index.rst

@@ -18,6 +18,7 @@ Contents:
    fusiondirectory/index.rst
    fusiondirectory-conf/index.rst
    fusiondirectory-tools/index.rst
+   fusiondirectory-orchestrator/index.rst
    fusiondirectory-webservice/index.rst
    support/index.rst
    security/index.rst

source/repositories/centos.rst

@@ -52,3 +52,15 @@ Add a file named **fusiondirectory-release.repo** in /etc/yum.repos.d/
   gpgcheck=1
   gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-FUSIONDIRECTORY
 
+To install FusionDirectory Orchestrator
+
+Add a file named **fusiondirectory-orchestrator-release.repo** in /etc/yum.repos.d/
+
+.. code-block:: shell
+
+  [fusiondirectory-orchestrator-release]
+  name=Fusiondirectory Packages for CentOS 7
+  baseurl=https://public.fusiondirectory.org/centos/centos7-fusiondirectory-rochestrator-release/RPMS
+  enabled=1
+  gpgcheck=1
+  gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-FUSIONDIRECTORY

source/repositories/debian.rst

@@ -26,8 +26,7 @@ Add a file named **fusiondirectory-external-libraries.list** in /etc/apt/sources
 
    #fusiondirectory libraries
    deb https://public.fusiondirectory.org/debian/fusiondirectory-external-libraries/ bullseye main
-
-
+ 
 Debian Buster
 ^^^^^^^^^^^^^
 
@@ -49,3 +48,12 @@ Add a file named **fusiondirectory-release.list** in /etc/apt/sources.list.d/
    #fusiondirectory repository
    deb https://public.fusiondirectory.org/debian/bullseye-fusiondirectory-release/ bullseye main
 
+To install FusionDirectory Orchestrator
+
+Add a file named **fusiondirectory-orchestrator-release.list** in /etc/apt/sources.list.d/
+
+.. code-block:: shell
+
+   #fusiondirectory Orchestrator repository
+   deb https://public.fusiondirectory.org/debian/bullseye-orchestrator-release/ bullseye main
+