diff -r 01d01045a2b7 -r 9049384a2bd4 docs/source/install.rst --- /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 `_ 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.