--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/source/install.rst Fri Nov 18 15:28:54 2016 +0100
@@ -0,0 +1,139 @@
+.. _install:
+
+Installing PyAMS
+================
+
+PyAMS default installation is based on `Buildout <http://www.buildout.org>`_ utility. It's not mandatory to use a
+virtual environment, but it allows you to have a better control over your Python resources.
+
+Current PyAMS version is based and validated for Python 3.4; your Python environment must also include a C
+compiler as well as development headers for Python, *libjpeg*, *libpng*, *libfreetype*, *libxml2*, *libxslt* and
+eventually *libldap* or *libzmq*.
+
+PyAMS default components configuration also pre-suppose that the following external tools are available:
+
+- a *memcached* server, to store sessions and cache (can be changed through Beaker configuration)
+
+Optional tools also include:
+
+- an *ElasticSearch* server for full text indexing (see *PyAMS_content_es* package)
+
+- a *WebSockets* server using async IO. 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_asyncio* scaffold provided by *pyams_base*
+ package.
+
+
+You can also choose to use a local ZODB instance, or a ZEO server (which can be local or remote, but is required if
+you want to use PyAMS in a muti-processes configuration).
+
+
+Creating initial buildout
+-------------------------
+
+PyAMS provides a new Pyramid scaffold, called *pyams*, provided by the *pyams_base* package.
+
+A simple option to install PyAMS is to create a buildout environment including *Pyramid* and *PyAMS_base* packages:
+
+.. code-block:: bash
+
+ # mkdir /var/local/env/
+ # pip3 install virtualenv
+ # virtualenv --python=python3.4 pyams
+ # cd pyams
+ # . bin/activate
+ (pyams) # pip3.4 install zc.buildout
+ (pyams) # buildout init
+
+Then update your Buildout configuration file *buildout.cfg* as follow:
+
+.. code-block:: ini
+
+ [buildout]
+ find-links = http://download.ztfy.org/eggs
+ extends = http://download.ztfy.org/pyams/pyams-0.1.0.cfg
+ socket-timeout = 3
+ show-picked-versions = true
+ newest = false
+ allow-hosts =
+ *.python.org
+ *.sourceforge.net
+ github.com
+ bitbucket.org
+ versions = versions
+ eggs-directory = eggs
+ parts = pyramid
+
+ [pyramid]
+ recipe = zc.recipe.egg
+ dependent-scripts = true
+ eggs =
+ pyramid
+ pyams_base
+ interpreter = py3.4
+
+Then launch the buildout initialization:
+
+.. code-block:: bash
+
+ (pyams) # ./bin/buildout
+ (pyams) # ./bin/pcreate -l
+ Available scaffolds:
+ alchemy: Pyramid project using SQLAlchemy, SQLite, URL dispatch, and
+ pyams: Pyramid project using all PyAMS packages
+ starter: Pyramid starter project using URL dispatch and Chameleon
+ zodb: Pyramid project using ZODB, traversal, and Chameleon
+ (pyams) # ./bin/pcreate -t pyams myapp
+ (pyams) # cd myapp
+
+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. Then finalize Bootstrap initialization:
+
+.. code-block:: bash
+
+ (pyams) # ../bin/buildout bootstrap
+ (pyams) # ./bin/buildout
+
+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.
+
+
+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 ZODB or a ZEO cache
+
+- a set of configuration files, in the *etc* directory; here are standard *development.ini* and *production.ini*
+ configuration files, two ZODB configuration files (*zodb.conf.fs* for a single FileStorage application process, and
+ *zodb.conf.zeo* for a ZEO client storage; default configuration defined in INI files is based on a single file
+ 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!
+
+
+Initializing the database
+-------------------------
+
+When 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
+
+ (pyams) # ./bin/pyams_upgrade etc/development.ini
+
+This process requires that every package is correctly included into *pyramid.includes* directive from selected
+configuration file.