Improved documentation regarding Mentat installation an quick start tutorial.

(Redmine issue: #3361)

doc/sphinx/_doclib/installation.rst

@@ -24,19 +24,30 @@ System dependencies
     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
+    In Mentat system it is used 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.
+`PostgreSQL <https://www.postgresql.org>`__
+    PostgreSQL is a powerful, open source object-relational database system. It
+    has more than 15 years of active development and a proven architecture that
+    has earned it a strong reputation for reliability, data integrity, and
+    correctness. It runs on all major operating systems, including Linux,
+    UNIX (AIX, BSD, HP-UX, macOS, Solaris), and Windows. It is fully ACID
+    compliant, has full support for foreign keys, joins, views, triggers, and
+    stored procedures (in multiple languages). It includes most SQL:2008 data
+    types, including INTEGER, NUMERIC, BOOLEAN, CHAR, VARCHAR, DATE, INTERVAL,
+    and TIMESTAMP. It also supports storage of binary large objects, including
+    pictures, sounds, or video. It has native programming interfaces for C/C++,
+    Java, .Net, Perl, Python, Ruby, Tcl, ODBC, among others, and exceptional
+    documentation.
 
-    It is used in Mentat system as backend service for persistent data storage.
+    In Mentat system it is used 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/>`__
+    * `Documentation <https://www.postgresql.org/docs/>`__
+    * `Installation guide for Debian systems <https://www.postgresql.org/download/linux/debian/>`__
 
 
 Python dependencies
@@ -57,9 +68,18 @@ Following is a list of all current Python dependencies:
 `pymongo <https://pypi.python.org/pypi/pymongo>`__
     Python driver for `MongoDB <http://www.mongodb.org>`__.
 
+`psycopg2 <https://pypi.python.org/pypi/psycopg2>`__
+    Python driver for `PostgreSQL <http://www.postgresql.org>`__.
+
+`sqlalchemy <https://pypi.python.org/pypi/SQLAlchemy/1.1.15>`__
+    Python universal DBAL and ORM toolkit.
+
 `rrdtool <https://pypi.python.org/pypi/rrdtool>`__
     Python bindings for `RRDTool <http://oss.oetiker.ch/rrdtool/>`__.
 
+`Flask <https://pypi.python.org/pypi/Flask>`__
+    Awesome Python `microframework <http://flask.pocoo.org/>`__ for web development.
+
 `ipranges <https://pypi.python.org/pypi/ipranges>`__
     Python library for working with IP addressess.
 
@@ -96,7 +116,7 @@ The installation is pretty straightforward, please follow these simple steps:
 
 .. code-block:: shell
 
-    # Step 1: Install and configure MongoDB database.
+    # Step 1: Install and configure PostgreSQL database. See official documentation.
 
     # 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
@@ -113,9 +133,15 @@ The installation is pretty straightforward, please follow these simple steps:
     # Step 6: Install the Mentat system:
     apt-get install mentat-ng
 
-    # STep 7: Install additional Python requirements:
+    # Step 7: Install additional Python requirements:
     pip3 install -r /etc/mentat/requirements.pip --upgrade
 
+    # Step 8: Download IP geolocation databases:
+    /etc/mentat/scripts/fetch-geoipdb.sh
+
+    # Step 9: Initialize PostgreSQL database schema:
+    mentat-dbmngr.py --command init
+
 
 Directory layout
 --------------------------------------------------------------------------------
@@ -151,15 +177,11 @@ appropriate driver for *apt*:
     apt-get install apt-transport-https
 
 
-Installing *pip3* manually using *setuptools*
+Installing *pip3* manually using *get-pip.py*
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you run into issues with *pip3*, because your native packaging system contains
+If you run into issues with *get-pip.py*, 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
+you might opt to uninstall the Debian version of *pip3* and install latest manually.
 
-    apt-get remove python3-pip
-    apt-get install python3-setuptools
-    easy_install3 pip
+* `Guidelines for installation <https://pip.pypa.io/en/stable/installing/>`__

doc/sphinx/_doclib/quickstart.rst

+.. _section-quickstart:
+
+Quickstart
+================================================================================
+
+First thing you can do after successfull :ref:`installation <section-installation>`
+is to check the status of all Mentat system modules:
+
+.. code-block:: shell
+
+    # The 'status' command is default, so this is a short form:
+    mentat-controller.py
+
+    # And the same, but more verbose:
+    mentat-controller.py --command status
+
+    # Or even:
+    mentat-controller.py --command=status
+
+All Mentat modules display help when executed with proper option:
+
+.. code-block:: shell
+
+    # Most interesting Mentat modules for the beginning:
+    mentat-controller.py --help
+    mentat-inspector.py --help
+    mentat-enricher --help
+    mentat-storage --help
+    mentat-cleanup.py --help
+    mentat-ideagen.py --help
+    mentat-statistician --help
+    ...
+
+Let`s start things up:
+
+.. code-block:: shell
+
+    # Start real-time message processing modules:
+    mentat-controller.py --command start
+
+    # Enable cron-based message post-processing modules:
+    mentat-controller.py --command enable
+
+At this point all default Mentat modules should be running. You can verify that
+fact by listing processes, tailing log files, or using the status command introduced
+above:
+
+.. code-block:: shell
+
+    # List all Mentat related processes:
+    ps aux | grep mentat
+
+    # Tail log files of Mentat real-time message processing modules:
+    tail -f /var/mentat/log/mentat-inspector.py.log
+    tail -f /var/mentat/log/mentat-enricher.py.log
+    tail -f /var/mentat/log/mentat-storage.py.log
+
+    # Check the status with Mentat control script:
+    mentat-controller.py
+
+Now it is time to generate some dummy test data:
+
+.. code-block:: shell
+
+    # Generate 1000 random test IDEA messages:
+    mentat-ideagen.py --count 1000
+
+And now verify, that IDEA messages indeed ended up in database:
+
+    su postgres
+    psql
+    \c mentat_events
+    SELECT * FROM mentat_events;

doc/sphinx/manual.rst

@@ -26,6 +26,7 @@ Contents:
 
    _doclib/architecture.rst
    _doclib/installation.rst
+   _doclib/quickstart.rst
    _doclib/bin.rst
    _doclib/hawat.rst
    _doclib/api.rst