--- a/src/source/plugins.rst Wed May 16 12:00:26 2018 +0200
+++ b/src/source/plugins.rst Wed May 16 14:06:43 2018 +0200
@@ -1,16 +1,16 @@
.. _plugins:
PyAMS additional features and services
-++++++++++++++++++++++++++++++++++++++
+======================================
-Elasticsearch 5.4
-=================
+Elasticsearch
++++++++++++++
-At first you need to install ElasticSearch (ES), currently PyAMS is compatible with the version 5.4, the Ingest attachment
+At first you need to install ElasticSearch (ES); PyAMS is actually compatible with version 5.4. The Ingest attachment
plug-in is also required to handle attachments correctly.
-Visit https://www.elastic.co/ to learn how to install Elasticsearch Server, and how install `ingest-attachment` plug-in
+Visit https://www.elastic.co/ to learn how to install Elasticsearch Server and `ingest-attachment` plug-in
.. tip:: Documentation for installing ElasticSearch 5.4
@@ -19,7 +19,8 @@
- https://www.elastic.co/guide/en/elasticsearch/plugins/5.4/ingest-attachment.html
-After ElasticSearch installation, following steps describe how to configure ES with PyAMS;
+After Elasticsearch installation, following steps describe how to configure ES with PyAMS.
+
Initializing Elasticsearch index
--------------------------------
@@ -28,30 +29,48 @@
Elasticsearch integration is defined through the *PyAMS_content_es* package.
-1. Enable Service:
-''''''''''''''''''
+1. Enable service
+'''''''''''''''''
-In Pyramid INI application file *(etc/development.ini)*:
+In Pyramid INI application files (*etc/development.ini* and *etc/production.ini*):
-.. code-block:: bash
+.. code-block:: ini
- # ElasticSearch settings
+ # Elasticsearch server settings
elastic.server = http://127.0.0.1:9200
elastic.index = pyams
-.. code-block:: bash
+Where:
+ - **elastic.server**: address of Elasticsearch server; you can include authentication arguments in the form
+ *http://login:password@w.x.y.z:9200*
+ - **elastic.index**: name of Elasticsearch index.
+
- # PyAMS content elasticsearch index settings
+On startup, main PyAMS application process can start in *indexer* process which will handle indexing requests in
+asynchronous mode; this process settings are defined like this:
+
+.. code-block:: ini
+
+ # PyAMS content Elasticsearch indexer process settings
pyams_content.es.tcp_handler = 127.0.0.1:5557
pyams_content.es.start_handler = false
pyams_content.es.allow_auth = admin:admin
pyams_content.es.allow_clients = 127.0.0.1
+Where:
+ - **pyams_content.es.tcp_handler**: IP address and listening port of PyAMS indexer process
+ - **pyams_content.es.start_handler**: if *true*, the indexer process is started on PyAMS startup; otherwise (typically
+ in a cluster configuration), the process is supposed to be started from another *master* server
+ - **pyams_content.es.allow_auth**: login and password to be used to connect to indexer process (settings are defined
+ in the same way on indexer process and on all it's clients)
+ - **pyams_content.es.allow_clients**: list of IP addresses allowed to connect to indexer process.
-2. Initialize Elasticsearch Database:
-'''''''''''''''''''''''''''''''''''''
-Configuration files for attachment pipeline, index settings and mappings are available `pyams_content_es` package or in PyAMS installation folder:
+2. Initialize Elasticsearch database
+''''''''''''''''''''''''''''''''''''
+
+Configuration files for attachment pipeline, index and mappings settings are available into `pyams_content_es` source
+package or in PyAMS installation folder:
.. code-block:: bash
@@ -60,7 +79,7 @@
(env) $ curl --noproxy localhost -XPUT http://localhost:9200/_ingest/pipeline/attachment -d @attachment-pipeline.json
-With ``elastic.index = pyams`` defined as Elasticsearch index name : *"http://localhost:9200/pyams"* :
+And with ``elastic.index = pyams`` defined as Elasticsearch index name: *"http://localhost:9200/pyams"*:
.. code-block:: shell
@@ -73,13 +92,14 @@
(env) $ curl -XPUT http://localhost:9200/pyams/WfBlogPost/_mapping -d @mappings/WfBlogPost.json
-*Troubleshooting*: If you have a 406 error try to add ``-H 'Content-Type: application/json'`` in curl option
+*Troubleshooting*: If you have a 406 error try to add ``-H 'Content-Type: application/json'`` in Curl command lines.
-3. Create or update index:
-''''''''''''''''''''''''''
+3. Update index contents
+''''''''''''''''''''''''
-You have to Update ElasticSearch indexes with all database contents with ``pymas_es_index``. From a shell:
+If your ZODB database already store contents, you can update ElasticSearch indexes with all these contents with
+``pymas_es_index`` command line script. From a shell:
.. code-block:: bash
@@ -87,29 +107,25 @@
--------------------------------
+Natural Language Toolkit - NLTK
++++++++++++++++++++++++++++++++
-Natural Language Toolkit - NLTK
-===============================
-
-
-PyAMS enjoy the NLTK features through the *PyAMS_calalog*
+PyAMS is using NLTK features through the *PyAMS_calalog*.
.. seealso::
Visit https://www.nltk.org/ to learn more about NLTK
-
-Initializing NLTK (Natural Language Toolkit)
+Initializing NLTK (Natural Language ToolKit)
--------------------------------------------
-Some NLTK Collections like **tokenizers** and **stopwords** utilities are used to index fulltext contents
-elements. You can enhanced NTKL indexation according to your own needs. This package requires downloading and
+Some NLTK collections like **tokenizers** and **stopwords** utilities are used to index fulltext contents
+elements. You can enhance NLTK indexation according to your own needs. This package requires downloading and
configuration of several elements which are done as follow:
-*1. Run the Python shell with PyAMS environment:*
+*1. Run the Python shell into PyAMS environment:*
.. code-block:: bash
@@ -132,7 +148,7 @@
Pyramid application), '*/usr/share/nltk_data*', '*/usr/local/share/nltk_data*', '*/usr/lib/nltk_data*' and
'*/usr/local/lib/nltk_data*'
- Please check if you have permission to write to this directory
+ Please check if you have permission to write to this directory!
.. code-block:: shell
@@ -190,4 +206,4 @@
.. tip::
- The full list of NTLK Collection are displayable with the ``l) list`` option
+ The full list of NTLK Collection can be displayed with the ``l) list`` option.