~therp-nl/anybox.recipe.openerp/jbaudoux-relative_paths_resolve_conflict

« back to all changes in this revision

Viewing changes to doc/first_steps.rst

[MRG] Update with target branch

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
First steps
 
2
===========
 
3
 
 
4
 
 
5
.. _howto:
 
6
 
 
7
How to create and bootstrap a buildout
 
8
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
9
 
 
10
To create a buildout and run the build, you just need **1 file** and **2 commands**:
 
11
 
 
12
- Create a single ``buildout.cfg`` file.
 
13
- Be sure you installed all your build dependencies
 
14
- Bootstrap the buildout with: ``python bootstrap.py``
 
15
- Run the build with: ``bin/buildout``
 
16
 
 
17
The same with more details below :
 
18
 
 
19
Creating the buildout
 
20
---------------------
 
21
 
 
22
Create a ``buildout.cfg`` file in an empty directory, containing the
 
23
configuration of the `example 6.1`_ section.
 
24
 
 
25
.. _dependencies:
 
26
 
 
27
Installing build dependencies
 
28
-----------------------------
 
29
 
 
30
You basically need typical development tools needed to build all the Python
 
31
dependency eggs of OpenERP. You can do this by yourself with your system or
 
32
Linux distribution.
 
33
 
 
34
Or if you're using a Debian based distribution, we provide a single
 
35
dependency package you can use to install all dependencies in one shot:
 
36
 
 
37
Add the following line in your ``/etc/apt/sources.list``::
 
38
 
 
39
  deb http://apt.anybox.fr/openerp common main
 
40
 
 
41
If you don't want your system to complain about non-signed packages,
 
42
have it accept the signing key, e.g. by issuing::
 
43
 
 
44
  sudo apt-key adv --keyserver hkp://subkeys.pgp.net --recv-keys 0xE38CEB07
 
45
 
 
46
(sometimes, the key server is too busy, you may need to wait a few
 
47
minutes and try again)
 
48
 
 
49
Install the dependency package::
 
50
 
 
51
  $ sudo aptitude update
 
52
  $ sudo aptitude install openerp-server-system-build-deps
 
53
 
 
54
You can uninstall this package with ``aptitude`` after the build to
 
55
automatically remove all un-needed dependencies, but you need to
 
56
install *run dependencies* before that ::
 
57
 
 
58
  $ sudo aptitude install openerp-server-system-run-deps
 
59
  $ sudo aptitude remove openerp-server-system-build-deps
 
60
 
 
61
Please note that these package will have your system install the
 
62
*client* part of PostgreSQL software only. If you want a
 
63
PostgreSQL server on the same host, that's not in the recipe scope,
 
64
just install it as well.
 
65
 
 
66
Bootstrapping the buildout
 
67
--------------------------
 
68
Bootstrapping the buildout consists in creating the basic structure of
 
69
the buildout, and installing buildout itself in the directory.
 
70
Once it's been done, everything is under tight control.
 
71
 
 
72
The easiest way to bootstrap is to use the ``bootstrap.py`` script::
 
73
 
 
74
  $ wget https://raw.github.com/buildout/buildout/master/bootstrap/bootstrap.py
 
75
 
 
76
As of zc.buildout version 2.2, strong isolation from the system-wide Python
 
77
installation has been abandoned because of its redundancy with the
 
78
very popular `virtualenv <https://pypi.python.org/pypi/virtualenv>`_.
 
79
Besides, the bootstrap actually fails if a version of
 
80
setuptools older than 0.7 is present system-wide (happens easily
 
81
enough at the time of this writing).
 
82
 
 
83
The universal current way of doing is therefore to start from a
 
84
virtualenv *without setuptools*. For virtualenv >= 1.9, just do::
 
85
 
 
86
  $ virtualenv sandbox --no-setuptools
 
87
 
 
88
For older versions of virtualenv::
 
89
 
 
90
  $ virtualenv sandbox
 
91
  $ sandbox/bin/pip uninstall setuptools pip
 
92
 
 
93
.. note:: to install virtualenv.
 
94
 
 
95
          * Debian family: sudo aptitude install python-virtualenv
 
96
          * Redhat/Fedora/CenOS family: sudo yum install python-virtualenv
 
97
 
 
98
Finally, perform the bootstrap with the virtualenv's Python::
 
99
 
 
100
  $ sandbox/bin/python bootstrap.py
 
101
 
 
102
From now on, all buildout related operations, including OpenERP
 
103
startup script, custom scripts will be protected by this virtualenv.
 
104
 
 
105
.. note:: nothing, not even ``zc.buildout`` actually gets installed by
 
106
          buildout in such a virtualenv.
 
107
          It's *totally safe* if you're managing several buildouts to
 
108
          share a single such virtualenv among all of them.
 
109
 
 
110
.. note:: since the bootstrap operation is so sensitive, we recommend
 
111
          package managers to include the precise ``bootstrap.py`` in
 
112
          their distributed buildout, and to bundle a future-proof
 
113
          shell script, using options such as ``-v``.
 
114
 
 
115
 
 
116
Running the build
 
117
-----------------
 
118
 
 
119
Just run ::
 
120
 
 
121
  $ bin/buildout
 
122
 
 
123
Starting OpenERP
 
124
----------------
 
125
 
 
126
Just run ::
 
127
 
 
128
  $ bin/start_openerp
 
129
 
 
130
.. _example 7.0:
 
131
 
 
132
Example OpenERP 7.0 buildouts
 
133
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
134
This example builds the latest nightly OpenERP 7 version.
 
135
Note how most Python distribution versions are pinned.
 
136
 
 
137
While not mandatory, version pinning is an
 
138
important part of the buildout culture. Note also how even ``zc.buildout``
 
139
and the current recipe versions can be pinned::
 
140
 
 
141
  [buildout]
 
142
  parts = openerp
 
143
  versions = versions
 
144
  find-links = http://download.gna.org/pychart/
 
145
 
 
146
  [openerp]
 
147
  recipe = anybox.recipe.openerp[bzr]:server
 
148
  version = nightly 7.0 latest
 
149
 
 
150
  [versions]
 
151
  setuptools = 1.1.0
 
152
  zc.buildout = 2.2.1
 
153
  zc.recipe.eggs = 2.0.0
 
154
  anybox.recipe.openerp = 1.7.1
 
155
  babel = 0.9.6
 
156
  Pillow = 1.7.1
 
157
  pywebdav = 0.9.4.1
 
158
  PyXML = 0.8.4
 
159
  pyyaml = 3.10
 
160
  werkzeug = 0.8.3
 
161
  zsi = 2.0-rc3
 
162
  feedparser = 5.1.1
 
163
  gdata = 2.0.16
 
164
  lxml = 2.3.3
 
165
  psycopg2 = 2.4.4
 
166
  pydot = 1.0.28
 
167
  pyparsing = 1.5.6
 
168
  python-dateutil = 1.5
 
169
  python-ldap = 2.4.9
 
170
  python-openid = 2.2.5
 
171
  pytz = 2012b
 
172
  vatnumber = 1.0
 
173
  vobject = 0.8.1c
 
174
  xlwt = 0.7.3
 
175
 
 
176
Of course, installing the latest nightly release provided by OpenERP
 
177
is not really interesting. The flexibility is.
 
178
 
 
179
Here's an example with the latest versions of the 7.0 Bazaar branches
 
180
on Launchpad as lightweight checkouts (to avoid hour long downloads).
 
181
We don't repeat the ``buildout`` and ``versions`` sections::
 
182
 
 
183
  [openerp]
 
184
  recipe = anybox.recipe.openerp[bzr]:server
 
185
  version = bzr lp:openobject-server/7.0 openerp-7.0 last:1 bzr-init=lightweight-checkout
 
186
  addons = bzr lp:openobject-addons/7.0 addons-7.0 last:1 bzr-init=lightweight-checkout
 
187
           bzr lp:openerp-web/7.0 addons-web-7.0 last:1 subdir=addons bzr-init=lightweight-checkout
 
188
 
 
189
Now imagine how easily one can switch branches and redistribute a
 
190
ready-to-run buildout on some dedicated support branch, Git mirrors, etc.
 
191
 
 
192
The next example is on 6.1 and demonstrates both how to add specific addons
 
193
directories, and how uniform it is.
 
194
 
 
195
.. _example 6.1:
 
196
 
 
197
Example OpenERP 6.1 buildout with a custom addon
 
198
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
199
 
 
200
Here is a very simple example for a latest OpenERP 6.1 nightly and a
 
201
custom addon hosted on Bitbucket::
 
202
 
 
203
    [buildout]
 
204
    parts = openerp 
 
205
    versions = versions
 
206
    find-links = http://download.gna.org/pychart/
 
207
    
 
208
    [openerp]
 
209
    recipe = anybox.recipe.openerp:server
 
210
    version = nightly 6.1 latest
 
211
    addons = hg https://bitbucket.org/anybox/anytracker addons-at default
 
212
 
 
213
    [versions]
 
214
    MarkupSafe = 0.15
 
215
    Pillow = 1.7.7
 
216
    PyXML = 0.8.4
 
217
    babel = 0.9.6
 
218
    feedparser = 5.1.1
 
219
    gdata = 2.0.16
 
220
    lxml = 2.3.3
 
221
    mako = 0.6.2
 
222
    psycopg2 = 2.4.4
 
223
    pychart = 1.39
 
224
    pydot = 1.0.28
 
225
    pyparsing = 1.5.6
 
226
    python-dateutil = 1.5
 
227
    python-ldap = 2.4.9
 
228
    python-openid = 2.2.5
 
229
    pytz = 2012b
 
230
    pywebdav = 0.9.4.1
 
231
    pyyaml = 3.10
 
232
    reportlab = 2.5
 
233
    simplejson = 2.4.0
 
234
    vatnumber = 1.0
 
235
    vobject = 0.8.1c
 
236
    werkzeug = 0.8.3
 
237
    xlwt = 0.7.3
 
238
    zc.buildout = 1.5.2
 
239
    zc.recipe.egg = 1.3.2
 
240
    zsi = 2.0-rc3
 
241
 
 
242
 
 
243
.. note:: with OpenERP 6.1 the web client is natively included in the server as a
 
244
    simple module. In that case you don't need to write a separate part for the web
 
245
    client, unless that's what you really want to do.
 
246
 
 
247
 
 
248
Example OpenERP 6.0 buildout (server and clients)
 
249
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
250
 
 
251
Here is a sample buildout with version specification, 2 OpenERP servers (with
 
252
one using the latest 6.0 branch on the launchpad) using only NETRPC and
 
253
listening on 2 different ports, and 2 web clients::
 
254
 
 
255
    [buildout]
 
256
    parts = openerp1 web1 openerp2 web2
 
257
    #allow-picked-versions = false
 
258
    versions = versions
 
259
    find-links = http://download.gna.org/pychart/
 
260
    
 
261
    [openerp1]
 
262
    recipe = anybox.recipe.openerp:server
 
263
    version = 6.0.3
 
264
    options.xmlrpc = False
 
265
    options.xmlrpcs = False
 
266
    
 
267
    [web1]
 
268
    recipe = anybox.recipe.openerp:webclient
 
269
    version = 6.0.3
 
270
    
 
271
    [openerp2]
 
272
    recipe = anybox.recipe.openerp[bzr]:server
 
273
    version = bzr lp:openobject-server/6.0 openobject-server-6.x last:1
 
274
 
 
275
    options.xmlrpc = False
 
276
    options.xmlrpcs = False
 
277
    options.netrpc_port = 8170
 
278
    
 
279
    [web2]
 
280
    recipe = anybox.recipe.openerp:webclient
 
281
    version = 6.0.3
 
282
    global.openerp.server.port = '8170'
 
283
    global.server.socket_port = 8180
 
284
    
 
285
    [versions]
 
286
    MarkupSafe = 0.15
 
287
    Pillow = 1.7.7
 
288
    anybox.recipe.openerp = 0.9
 
289
    caldav = 0.1.10
 
290
    collective.recipe.cmd = 0.5
 
291
    coverage = 3.5
 
292
    distribute = 0.6.25
 
293
    feedparser = 5.0.1
 
294
    lxml = 2.1.5
 
295
    mako = 0.4.2
 
296
    nose = 1.1.2
 
297
    psycopg2 = 2.4.2
 
298
    pychart = 1.39
 
299
    pydot = 1.0.25
 
300
    pyparsing = 1.5.6
 
301
    python-dateutil = 1.5
 
302
    pytz = 2012b
 
303
    pywebdav = 0.9.4.1
 
304
    pyyaml = 3.10
 
305
    reportlab = 2.5
 
306
    vobject = 0.8.1c
 
307
    z3c.recipe.scripts = 1.0.1
 
308
    zc.buildout = 1.5.2
 
309
    zc.recipe.egg = 1.3.2
 
310
    Babel = 0.9.6
 
311
    FormEncode = 1.2.4
 
312
    simplejson = 2.1.6
 
313
 
 
314
Continuously tested examples
 
315
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
316
 
 
317
Other examples are available in the ``buildbot`` subdirectory of the
 
318
source distribution archive of this recipe (the ``tar.gz`` file that
 
319
can be downloaded `from the PyPI
 
320
<http://pypi.python.org/pypi/anybox.recipe.openerp>`_), and are
 
321
continuously tested in the
 
322
`anybox buildbot <http://buildbot.anybox.fr/>`_ which is powered by
 
323
`anybox.buildbot.openerp
 
324
<http://pypi.python.org/pypi/anybox.buildbot.openerp>`_.
 
325
 
 
326
See also :ref:`continuous_integration` for more details about these
 
327
tested examples.
 
328
 
 
329
Other sample buildouts
 
330
~~~~~~~~~~~~~~~~~~~~~~
 
331
 
 
332
Here are a few ready-to-use buildouts:
 
333
 
 
334
(Be sure to install system dependencies_ first)
 
335
 
 
336
OpenERP with the development branches of the Magento connector addons::
 
337
 
 
338
  $ hg clone https://bitbucket.org/anybox/openerp_connect_magento_buildout
 
339
  $ cd openerp_connect_magento_buildout
 
340
  $ python bootstrap.py
 
341
  $ bin/buildout
 
342
  $ bin/start_openerp
 
343
 
 
344
OpenERP with the development branches of the Prestashop connector addons::
 
345
 
 
346
  $ hg clone https://bitbucket.org/anybox/openerp_connect_prestashop_buildout
 
347
  $ cd openerp_connect_prestashop_buildout
 
348
  $ python bootstrap.py
 
349
  $ bin/buildout
 
350
  $ bin/start_openerp
 
351