--- a/src/source/admln_guide/appinstall.rst Tue Dec 11 17:00:42 2018 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,244 +0,0 @@
-.. _appinstall:
-
-.. _install:
-
-Installing PyAMS application
-============================
-
-**PyAMS** default installation is based on `Buildout <http://www.buildout.org>`_ utility.
-
-.. tip::
-
- Take a look at virtualenv_. This tool provide isolated Python environments, which are more practical than installing packages systemwide.
- They also allow installing packages without administrator privileges.
-
-.. _virtualenv: https://virtualenv.pypa.io/en/stable/
-
-
-Current PyAMS version is based and validated for **Python 3.5**; your Python environment must also include a **C compiler**
-as well as development headers for Python, *libjpeg*, *libpng*, *libfreetype*, *libxml2*, *libxslt* and
-eventually *libldap*, *libpq*, *libffi*, *libgdal* or *libzmq*. **Cython** compiler can also be useful to optimize
-several packages.
-
-
-.. note::
-
- PyAMS default components configuration also pre-suppose that the following external services are available.
-
- * Mandatory services:
-
- - a **ZODB shared server** (see :ref:`zodb` before). Several background processes needing a concurrent access to ZODB are started by PyAMS main process. Three ZODB storages are already provided through PyAMS: ZEO, RelStorage or Newt.db.
-
- - a **Memcached** or **Redis*** server, to store sessions and cache
-
- * Optional services:
-
- - an **LDAP server** for authentication
-
- - an **ElasticSearch server** for full text indexing (see *PyAMS_content_es* package)
-
- - a **WebSockets server** using AsyncIO. This is used to manage notifications (see *PyAMS_notify* and *PyAMS_notify_ws* packages). An *out of the box* environment can be built using *pyams_notify* scaffold.
-
-
-Creating initial buildout
--------------------------
-
-PyAMS provides a new Pyramid scaffold, called *pyams*, generated via a *cookiecutter* template.
-
-A simple option to install PyAMS is to create a buildout environment including *Pyramid* and all *PyAMS* packages:
-
-.. code-block:: bash
-
- $ mkdir /var/local/
- $ pip3 install virtualenv
- $ virtualenv --python=python3.5 env
- $ cd env
- $ . bin/activate
- (env) $ pip3.5 install cookiecutter
- (env) $ cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams
-
-*CookieCutter* will ask you for a small set of input variables that you can change or not (**parameter** [*default value*]:)
-
-- **pyams_release** [*latest*] : version of PyAMS configuration file to use. "latest" will point to last release;
- you can also choose to point to a given release ("0.1.4" for example)
-
-- **project_name** [*PyAMS*]: current environment name in "human form"
-
-- **project_slug**: [*pyams*] "technical" package name, based on project name
-
-- **virtual_hostname** [*pyams.mydomain.com*]: Apache virtual-host name
-
-- **webapp_name** [*webapps*]: web application package name
-
-- **webapp_port** [*6543*]: TCP/IP port to use when running application outside Apache.
-
-- **eggs_directory** [*eggs*]: relative or absolute path to directory containing downloaded eggs; this directory can be
- shared with other projects.
-
-- **logs_directory** [*/var/log*]: absolute path to directory containing Apache's log files
-
-- **run_user** [*www-data*]: user name under which Apache process will run
-
-- **run_group** [*www-data*]: group name under which Apache process will run
-
-- **beaker_backend** : name of Beaker backend to use to store sessions and cache data ("redis" as default)
-
-- **beaker_server** [*127.0.0.1:6379*]: IP address and port of Beaker backend server
-
-- **db_type** [*zeo*]: ZODB database storage; available options include ZEO, RelStorage and NewtDB
-
-- **db_host** [*127.0.0.1*]: IP address of database server ("127.0.0.1" as default); WARNING: database server installation
- is not part of application installation; another "zeo_server" cookiecutter recipe is available for ZEO
-
-- **db_port** [*8100*]: listening port of database server ("8100" is given as default for ZEO)
-
-- **db_name** [*pyams*]: database or ZEO storage name to use
-
-- **db_username**: database user name
-
-- **db_password**: database password
-
-- **zeo_realm**: ZEO authentication realm
-
-- **blobs_dir** [*/var/db/blobs*]: local directory to use to store cache of ZODB blobs; cache size is limited to 10GB as default
-
-- **use_postgresql**: specify if PostgreSQL access is required; if so, please check that PostgreSQL development files
- are available to compile PsycoPG2 extension
-
-- **use_oracle**: specify if Oracle access is required; if so, please check that Oracle development files are
- available to compile cx_Oracle extension, and that ORACLE_HOME environment variable is correctly defined (see below)
-
-- **use_ldap**: specify if LDAP access will be required for authentication
-
-- **use_elasticsearch**: specify if an ElasticSearch server will be used for indexation
-
-- **elasticsearch_server**: URL used to access Elasticsearch server ("http://127.0.0.1:9200" as default); this URL can
- include login and password ("http://login:password@127.0.0.1:9200"), if required...
-
-- **elasticsearch_index**: name of Elasticsearch index to use ("pyams" as default)
-
-- **create_elasticsearch_index**: specify if Elasticsearch index should be created after installation is complete
-
-- **define_elasticsearch_mappings** : specify if Elasticsearch mappings should be defined after installation is complete
-
-- **smtp_server**: DNS name of SMTP server ("localhost" as default)
-
-- **smtp_server_name**: "human" name given to SMTP server ("pyams" as default)
-
-- **pyams_scheduler** [*127.0.0.1:5555*]: TCP/IP address and port to use to access PyAMS tasks scheduler process (see :ref:`pyams_scheduler`)
-
-- **start_scheduler** [*True*]: boolean value to indicate if scheduler process is started by this application instance
-
-- **pyams_medias_converter** [*127.0.0.1:5556*]: TCP/IP address and port to use to access PyAMS medias converter process (see :ref:`pyams_media`)
-
-- **start_medias_converter** [*True*]: boolean value to indicate if medias converter process is started by this application
- instance
-
-- **pyams_es_indexer** [*127.0.0.1:5557*] : TCP/IP address and port to use to access PyAMS Elasticsearch indexer process (see :ref:`pyams_content_es`)
-
-- **start_es_indexer** boolean value to indicate if Elasticsearch indexer process is started by this application
- instance
-
-- **use_notifications**: specify if PyAMS notifications services are to be used (see :ref:`pyams_notify`)
-
-- **pyams_ws_notify** [*127.0.0.1:8081*]: TCP/IP address and port of PyAMS websockets server managing notifications service
-
-- **lexicon_languages**: NLTK lexicon languages to use ("en:english fr:french" as default)
-
-- **extension_package**: name of a PyAMS extension package to include in environment configuration
-
-- **need_pyams_gis**: specify if PyAMS GIS features are to be used by given extension package; if so, please check
- that *libgdal* development files are available; on Debian (and maybe others), you have to specify environment
- variables (see below).
-
-.. tip::
-
- 1. Setting any option to empty string will keep the default proposed value.
- 2. Boolean values accept "true", "yes", "on" or "1" (in any case) as *true* values, and anything else as *false*;
-
-You can then check, and eventually update, the proposed Buildout configuration file *buildout.cfg*, to add or remove
-packages or update settings to your needs.
-
-This last operation can be quite long, as many packages have to downloaded, compiled and installed in the virtual
-environment. If you encounter any compile error, just install the required dependencies and restart the buildout.
-
-Some dependencies can require the definition of custom environment variables before running *buildout*, like:
-
-- for *libgdal*, which is required by **PyAMS_gis** package, use:
-
-.. code-block:: bash
-
- (env) $ export C_INCLUDE_PATH=/usr/include/gdal
- (env) $ export CPLUS_INCLUDE_PATH=/usr/include/gdal
-
-
-.. WARNING::
- You have to check also that your *libgdal* release is matching "GDAL" release given in PyAMS
- configuration file (actually 2.1.0).
-
-- for *cx_Oracle*, which is required if you use Oracle database connections, use:
-
-.. code-block:: bash
-
- (env) $ export ORACLE_HOME=/usr/lib/oracle/12.1/client64
-
-These examples are given for Debian GNU/Linux. You may have to adapt configuration based on your own Linux
-distribution and packages versions.
-
-
-**Then finalize Bootstrap initialization:**
-
-.. code-block:: bash
-
- (env) $ python3.5 bootstrap.py
- (env) $ ./bin/buildout
-
-
-.. seealso::
-
- `zc.buildout <https://pypi.python.org/pypi/zc.buildout>`_ is a powerful
- tool for creating repeatable builds of a given software configuration
- and environment.
-
-
-Environment settings
---------------------
-
-The project generated from *pyams* scaffold is based on default Pyramid's *zodb* scaffold, but it adds:
-
-- a custom application factory, in the *webapp* directory (see :ref:`site`)
-
-- a set of directories to store runtime data, in the *var* directory; each directory contains a *README.txt* file
- which should be self-explanatory to indicate what this directory should contain, including a ZEO cache
-
-- a set of configuration files, in the *etc* directory; here are standard *development.ini* and *production.ini*
- configuration files, a ZODB configuration files (*zodb-zeo.conf*) for a ZEO client storage and two Apache
- configurations (for Apache 2.2 and 2.4) using *mod_wsgi*.
-
-Once the project have been created from the scaffold, you are free to update all the configuration files.
-
-If you need to add packages to the environment, you have to add them to the *buildout.cfg* file **AND** to the INI
-file (in the *pyramid.includes* section) before running the *buildout* another time; don't forget to add the
-requested version at the end of *buildout.cfg* file, as Buildout is not configured by default to automatically
-download the last release of a given unknown package.
-
-*development.ini* and *production.ini* files contain many commented directives related to PyAMS components. Read and
-update them carefully before initializing your application database!
-
-
-.. _zodbinit:
-
-Initializing the ZODB database
-------------------------------
-
-After, you have downloaded and installed all required packages, you have to initialize the database so that all
-required components are available.
-
-From a shell, just type:
-
-.. code-block:: bash
-
- (env) $ ./bin/pyams_upgrade etc/development.ini
-
-This process requires that every package is correctly included into *pyramid.includes* directive from selected
-configuration file.