docs/build/html/_sources/install.txt
changeset 78 54aeb42c0d80
equal deleted inserted replaced
77:13f3fb3fc4ef 78:54aeb42c0d80
       
     1 .. _install:
       
     2 
       
     3 Installing PyAMS
       
     4 ================
       
     5 
       
     6 PyAMS default installation is based on `Buildout <http://www.buildout.org>`_ utility. It's not mandatory to use a
       
     7 virtual environment, but it allows you to have a better control over your Python resources.
       
     8 
       
     9 Current PyAMS version is based and validated for Python 3.4; your Python environment must also include a C
       
    10 compiler as well as development headers for Python, *libjpeg*, *libpng*, *libfreetype*, *libxml2*, *libxslt* and
       
    11 eventually *libldap* or *libzmq*.
       
    12 
       
    13 PyAMS default components configuration also pre-suppose that the following external tools are available:
       
    14 
       
    15 - a *memcached* server, to store sessions and cache (can be changed through Beaker configuration)
       
    16 
       
    17 Optional tools also include:
       
    18 
       
    19 - an *ElasticSearch* server for full text indexing (see *PyAMS_content_es* package)
       
    20 
       
    21 - a *WebSockets* server using async IO. This is used to manage notifications (see *PyAMS_notify* and *PyAMS_notify_ws*
       
    22   packages). An *out of the box* environment can be built using *pyams_asyncio* scaffold provided by *pyams_base*
       
    23   package.
       
    24 
       
    25 
       
    26 You can also choose to use a local ZODB instance, or a ZEO server (which can be local or remote, but is required if
       
    27 you want to use PyAMS in a muti-processes configuration).
       
    28 
       
    29 
       
    30 Creating initial buildout
       
    31 -------------------------
       
    32 
       
    33 PyAMS provides a new Pyramid scaffold, called *pyams*, provided by the *pyams_base* package.
       
    34 
       
    35 A simple option to install PyAMS is to create a buildout environment including *Pyramid* and *PyAMS_base* packages:
       
    36 
       
    37 .. code-block:: bash
       
    38 
       
    39     # mkdir /var/local/env/
       
    40     # pip3 install virtualenv
       
    41     # virtualenv --python=python3.4 pyams
       
    42     # cd pyams
       
    43     # . bin/activate
       
    44     (pyams) # pip3.4 install zc.buildout
       
    45     (pyams) # buildout init
       
    46 
       
    47 Then update your Buildout configuration file *buildout.cfg* as follow:
       
    48 
       
    49 .. code-block:: ini
       
    50 
       
    51     [buildout]
       
    52     find-links = http://download.ztfy.org/eggs
       
    53     extends = http://download.ztfy.org/pyams/pyams-0.1.0.cfg
       
    54     socket-timeout = 3
       
    55     show-picked-versions = true
       
    56     newest = false
       
    57     allow-hosts =
       
    58         *.python.org
       
    59         *.sourceforge.net
       
    60         github.com
       
    61         bitbucket.org
       
    62     versions = versions
       
    63     eggs-directory = eggs
       
    64     parts = pyramid
       
    65 
       
    66     [pyramid]
       
    67     recipe = zc.recipe.egg
       
    68     dependent-scripts = true
       
    69     eggs =
       
    70         pyramid
       
    71         pyams_base
       
    72     interpreter = py3.4
       
    73 
       
    74 Then launch the buildout initialization:
       
    75 
       
    76 .. code-block:: bash
       
    77 
       
    78     (pyams) # ./bin/buildout
       
    79     (pyams) # ./bin/pcreate -l
       
    80     Available scaffolds:
       
    81       alchemy:  Pyramid project using SQLAlchemy, SQLite, URL dispatch, and
       
    82       pyams:    Pyramid project using all PyAMS packages
       
    83       starter:  Pyramid starter project using URL dispatch and Chameleon
       
    84       zodb:     Pyramid project using ZODB, traversal, and Chameleon
       
    85     (pyams) # ./bin/pcreate -t pyams myapp
       
    86     (pyams) # cd myapp
       
    87 
       
    88 You can then check, and eventually update, the proposed Buildout configuration file *buildout.cfg*, to add or remove
       
    89 packages or update settings to your needs. Then finalize Bootstrap initialization:
       
    90 
       
    91 .. code-block:: bash
       
    92 
       
    93     (pyams) # ../bin/buildout bootstrap
       
    94     (pyams) # ./bin/buildout
       
    95 
       
    96 This last operation can be quite long, as many packages have to downloaded, compiled and installed in the virtual
       
    97 environment. If you encounter any compile error, just install the required dependencies and restart the buildout.
       
    98 
       
    99 
       
   100 Environment settings
       
   101 --------------------
       
   102 
       
   103 The project generated from *pyams* scaffold is based on default Pyramid's *zodb* scaffold, but it adds:
       
   104 
       
   105 - a custom application factory, in the *webapp* directory (see :ref:`site`)
       
   106 
       
   107 - a set of directories to store runtime data, in the *var* directory; each directory contains a *README.txt* file
       
   108   which should be self-explanatory to indicate what this directory should contain, including a ZODB or a ZEO cache
       
   109 
       
   110 - a set of configuration files, in the *etc* directory; here are standard *development.ini* and *production.ini*
       
   111   configuration files, two ZODB configuration files (*zodb.conf.fs* for a single FileStorage application process, and
       
   112   *zodb.conf.zeo* for a ZEO client storage; default configuration defined in INI files is based on a single file
       
   113   storage) and two Apache configurations (for Apache 2.2 and 2.4) using *mod_wsgi*.
       
   114 
       
   115 Once the project have been created from the scaffold, you are free to update all the configuration files.
       
   116 
       
   117 If you need to add packages to the environment, you have to add them to the *buildout.cfg* file **AND** to the INI
       
   118 file (in the *pyramid.includes* section) before running the *buildout* another time; don't forget to add the
       
   119 requested version at the end of *buildout.cfg* file, as Buildout is not configured by default to automatically
       
   120 download the last release of a given unknown package.
       
   121 
       
   122 *development.ini* and *production.ini* files contain many commented directives related to PyAMS components. Read and
       
   123 update them carefully before initializing your application database!
       
   124 
       
   125 
       
   126 Initializing the database
       
   127 -------------------------
       
   128 
       
   129 When you have downloaded and installed all required packages, you have to initialize the database so that all
       
   130 required components are available.
       
   131 
       
   132 From a shell, just type:
       
   133 
       
   134 .. code-block:: bash
       
   135 
       
   136     (pyams) # ./bin/pyams_upgrade etc/development.ini
       
   137 
       
   138 This process requires that every package is correctly included into *pyramid.includes* directive from selected
       
   139 configuration file.