Added documentation page about installation.

(Redmine issue: #3361)

doc/sphinx/_doclib/installation.rst

+.. _section-installation:
+
+Installation
+================================================================================
+
+
+The Mentat system is available as package for Debian based systems via our custom
+internal repository. We are trying hard to keep the installation process as simple
+as possible, however at the same time we try not to force too many decisions. The
+Mentat system depends on couple of additional Debian system packages and Python
+libraries and some of those you have to install manually according to your preferences.
+Depending on your options you may use either native Debian system package management
+tools, or install the packages differently.
+
+
+Dependencies
+--------------------------------------------------------------------------------
+
+
+System dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`RRDTool <http://oss.oetiker.ch/rrdtool/>`__
+    The OpenSource industry standard, high performance data logging and graphing
+    system for time series data.
+
+    It is used in Mentat system for storing and displaying continuous system
+    processing performance statistics.
+
+    * `Documentation <http://oss.oetiker.ch/rrdtool/doc/index.en.html>`__
+    * `Debian packages <https://packages.debian.org/search?keywords=rrdtool>`_
+
+`MongoDB <https://www.mongodb.com/>`__
+    Document oriented NoSQL database.
+
+    It is used in Mentat system as backend service for persistent data storage.
+
+    * `Documentation <https://docs.mongodb.com/manual/>`__
+    * `Installation guide for Debian systems <https://docs.mongodb.com/manual/tutorial/install-mongodb-on-debian/>`__
+
+
+Python dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Following is a list of all current Python dependencies:
+
+`geoip2 <https://pypi.python.org/pypi/geoip2>`__
+    Python binding for `MaxMind <https://www.maxmind.com/en/home>`__
+    `GeoIP2 <http://dev.maxmind.com/geoip/geoip2/geolite2/>`__ API.
+
+`jinja2 <https://pypi.python.org/pypi/Jinja2>`__
+    A small but fast and easy to use stand-alone template engine written in pure Python.
+
+`ply <https://pypi.python.org/pypi/ply>`__
+    Python Lex & Yacc.
+
+`pymongo <https://pypi.python.org/pypi/pymongo>`__
+    Python driver for `MongoDB <http://www.mongodb.org>`__.
+
+`rrdtool <https://pypi.python.org/pypi/rrdtool>`__
+    Python bindings for `RRDTool <http://oss.oetiker.ch/rrdtool/>`__.
+
+`ipranges <https://pypi.python.org/pypi/ipranges>`__
+    Python library for working with IP addressess.
+
+`typedcols <https://pypi.python.org/pypi/typedcols>`__
+    Python library providing typed collections.
+
+`idea-format <https://pypi.python.org/pypi/pydgets>`__
+    Python library for working with `IDEA <https://idea.cesnet.cz/en/index>` messages.
+
+`Pydgets <https://pypi.python.org/pypi/pydgets>`__
+    Python3 command line widget library.
+
+`PyZenKit <https://pypi.python.org/pypi/pyzenkit>`__
+    Collection of usefull tools and utilities for creating console applications,
+    scripts and system services (daemons) in Python 3.
+
+`Pynspect <https://pypi.python.org/pypi/pynspect>`__
+    Python library for filtering, querying or inspecting almost arbitrary data
+    structures.
+
+All these dependencies can be quickly installed using ``pip3`` and prepared Python
+requirements file ``/etc/mentat/requirements.pip``:
+
+.. code-block:: shell
+
+    pip3 install -r /etc/mentat/requirements.pip --upgrade
+
+
+Installation guide
+--------------------------------------------------------------------------------
+
+The installation is pretty straightforward, please follow these simple steps:
+
+
+.. code-block:: shell
+
+    # Step 1: Install and configure MongoDB database.
+
+    # Step 2: Download apt list file for mentat production package repository:
+    wget -O /etc/apt/sources.list.d/mentat-production.list https://alchemist.cesnet.cz/mentat/deb/mentat-production.list
+
+    # Step 3: Download and install GnuPG signing key for mentat production package repository:
+    wget -O - https://alchemist.cesnet.cz/mentat/deb/mentat-production.gpg | apt-key add -
+
+    # Step 4: Refresh apt cache:
+    apt-get update
+
+    # Step 5: List all packages available in newly added repository (optional):
+    grep "Package:" /var/lib/apt/lists/alchemist.cesnet.cz_*mentat*_Packages | uniq
+
+    # Step 6: Install the Mentat system:
+    apt-get install mentat-ng
+
+    # STep 7: Install additional Python requirements:
+    pip3 install -r /etc/mentat/requirements.pip --upgrade
+
+
+Directory layout
+--------------------------------------------------------------------------------
+
+===============  ==========
+Location         Content
+===============  ==========
+/etc/mentat      Configuration files for Mentat modules.
+/etc/cron.d      Some Mentat modules are launched periodically via *cron*.
+/var/mentat      Working directory for all Mentat modules. Pid files, runlogs, log files and other runtime data is located inside this directory.
+/usr/local/bin   Executable files.
+===============  ==========
+
+
+Troubleshooting
+--------------------------------------------------------------------------------
+
+
+Installing *HTTPS* driver for *apt*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You might encounter following error when trying to install *mentat-ng* Debian package:
+
+.. code-block:: shell
+
+    E: The method driver /usr/lib/apt/methods/https could not be found.
+
+The problem is, that our Debian are server over *HTTPS* and you have to install
+appropriate driver for *apt*:
+
+.. code-block:: shell
+
+    apt-get install apt-transport-https
+
+
+Installing *pip3* manually using *setuptools*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you run into issues with *pip3*, because your native packaging system contains
+older versions and you are attempting to install a package requiring newer version,
+you might opt to uninstall the Debian version of *pip3* and install latest manually:
+
+.. code-block:: shell
+
+    apt-get remove python3-pip
+    apt-get install python3-setuptools
+    easy_install3 pip

doc/sphinx/manual.rst

@@ -24,6 +24,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   _doclib/installation.rst
    _doclib/bin.rst
    _doclib/api.rst