|
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. |