setup.rst 12.2 KB
Newer Older
1
.. -*- coding: utf-8 -*-
Adrien Di Mascio's avatar
Adrien Di Mascio committed
2

Sandrine Ribeau's avatar
Sandrine Ribeau committed
3
.. _SetUpEnv:
Adrien Di Mascio's avatar
Adrien Di Mascio committed
4

Nicolas Chauvat's avatar
Nicolas Chauvat committed
5
Installation and set-up of a *CubicWeb* environment
6
===================================================
Adrien Di Mascio's avatar
Adrien Di Mascio committed
7

8
9
10
Installation of `Cubicweb` and its dependencies
-----------------------------------------------

Nicolas Chauvat's avatar
Nicolas Chauvat committed
11
*CubicWeb* is packaged for Debian and Ubuntu, but can be installed from source
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
using a tarball or the Mercurial version control system.

.. _DebianInstallation:

Debian and Ubuntu packages
```````````````````````````

Depending on the distribution you are using, add the appropriate line to your list
of sources (for example by editing ``/etc/apt/sources.list``).

For Debian Lenny::

  deb http://ftp.logilab.org/dists/ lenny/

For Debian Sid::

  deb http://ftp.logilab.org/dists/ sid/

For Ubuntu Hardy::

  deb http://ftp.logilab.org/dists/ hardy/


You can now install the required packages with the following command::

Nicolas Chauvat's avatar
Nicolas Chauvat committed
37
  apt-get update
38
39
40
  apt-get install cubicweb cubicweb-dev

`cubicweb` installs the framework itself, allowing you to create
41
new instances.
42
43
44
45
46
47

`cubicweb-dev` installs the development environment allowing you to
develop new cubes.

There is also a wide variety of cubes listed on http://www.cubicweb.org/Project available as debian packages and tarball.

48
The repositories are signed with `Logilab's gnupg key`_. To avoid warning on "apt-get update":
Aurelien Campeas's avatar
Aurelien Campeas committed
49
1. become root using sudo
50
51
52
53
2. download http://ftp.logilab.org/dists/logilab-dists-key.asc using e.g. wget
3. run "apt-key add logilab-dists-key.asc"
4. re-run apt-get update (manually or through the package manager, whichever you prefer)

54
.. _`Logilab's gnupg key`: http://ftp.logilab.org/dists/logilab-dists-key.asc
55

Adrien Chauve's avatar
Adrien Chauve committed
56
57
.. _SourceInstallation:

58
59
60
61
62
63
64
65
66
Install from source
```````````````````

You can download the archive containing the sources from our `ftp site`_ at::

  http://ftp.logilab.org/pub/cubicweb/

.. _`ftp site`: http://ftp.logilab.org/pub/cubicweb/

67
68
69
70
71
72
73
Make sure you have installed the dependencies (see appendixes for the list).

Install from version control system
```````````````````````````````````

You can keep up to date with on-going development by using Mercurial and its
forest extension::
74
75
76
77

  hg fclone http://www.logilab.org/hg/forests/cubicweb

See :ref:`MercurialPresentation` for more details about Mercurial.
78

Aurelien Campeas's avatar
Aurelien Campeas committed
79
80
81
82
When cloning a repository, you might be set in a development branch
(the 'default' branch). You should check that the branches of the
repositories are set to 'stable' (using `hg up stable` for each one)
if you do not intend to develop the framework itself.
83

84
85
86
Do not forget to update the forest itself (using `cd path/to/forest ; hg up`).

Make sure you have installed the dependencies (see appendixes for the list).
87

Adrien Chauve's avatar
Adrien Chauve committed
88
89
.. _WindowsInstallation:

90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
Windows installation
````````````````````

Base elements
_____________

Setting up a windows development environment is not too complicated
but requires a series of small steps. What is proposed there is only
an example of what can be done. We assume everything goes into C:\ in
this document. Adjusting the installation drive should be
straightforward.

You should start by downloading and installing the Python(x,y)
distribution. It contains python 2.5 plus numerous useful third-party
modules and applications::

  http://www.pythonxy.com/download_fr.php

At the time of this writting, one gets version 2.1.15. Among the many
things provided, one finds Eclipse + pydev (an arguably good IDE for
python under windows).

Then you must grab Twisted. There is a windows installer directly
available from this page::

  http://twistedmatrix.com/trac/

A windows installer for lxml will be found there::

  http://pypi.python.org/pypi/lxml/2.2.1

Check out the lxml-2.2.1-win32-py2.5.exe file. More recent bugfix
releases should probably work, too.

You should find postgresql 8.4 there::

  http://www.enterprisedb.com/products/pgdownload.do#windows

The python drivers for posgtresql are to be found there::

  http://www.stickpeople.com/projects/python/win-psycopg/#Version2

Please be careful to select the right python (2.5) and postgres (8.4)
versions.

135
Pyro enables remote access to cubicweb repository instances. Get it
Aurelien Campeas's avatar
Aurelien Campeas committed
136
137
138
139
there::

  http://sourceforge.net/projects/pyro/files/

140
141
142
143
144
145
146
To access LDAP/Active directory directories, we need the python-ldap
package. Windows binaries are available from::

  http://www.osuch.org/python-ldap

Check out the latest release.

147
148
149
150
151
Having graphviz will allow schema drawings, which is quite recommended
(albeit not mandatory). You should get an msi installer there::

  http://www.graphviz.org/Download_windows.php

152
153
154
155
156
Simplejson will be provided within the forest, but a win32 compiled
version will run much faster::

  http://www.osuch.org/python-simplejson%3Awin32

157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
Tools
_____

Get mercurial + its standard windows GUI (TortoiseHG) there (the
latest is the greatest)::

  http://bitbucket.org/tortoisehg/stable/wiki/download

If you need to peruse mercurial over ssh, it can be helpful to get an
ssh client like Putty::

  http://www.putty.org/

Integration of mercurial and Eclipse is convenient enough that we want
it. Instructions are set there, in the `Download & Install` section::

  http://www.vectrace.com/mercurialeclipse/

Setting up the sources
______________________

You need to enable the mercurial forest extension. To do this, edit
the file::

  C:\Program Files\TortoiseHg\Mercurial.ini

In the [extensions] section, add the following line::

  forest=C:\Program Files\TortoiseHg\ext\forest\forest.py

Now, you need to clone the cubicweb repository. We assume that you use
Eclipse. From the IDE, choose File -> Import. In the box, select
`Mercurial/Clone repository using MercurialEclipse`.

In the import main panel you just have to:

* fill the URL field with http://www.logilab.org/hg/forests/cubicwin32

* check the 'Repository is a forest' box.

Then, click on 'Finish'. It might take some time to get it all. Note
that the `cubicwin32` forest contains additional python packages such
as yapps, vobject, simplejson and twisted-web2 which are not provided
with Python(x,y). This is provided for convenience, as we do not
ensure the up-to-dateness of these packages, especially with respect
to security fixes.

Environment variables
_____________________

You will need some convenience environment variables once all is set
up. These variables are settable through the GUI by getting at the
'System properties' window (by righ-clicking on 'My Computer' ->
properties).

In the 'advanced' tab, there is an 'Environment variables'
button. Click on it. That opens a small window allowing edition of
user-related and system-wide variables.

We will consider only user variables. First, the PATH variable. You
should ensure it contains, separated by semi-colons, and assuming you
are logged in as user Jane::

  C:\Documents and Settings\Jane\My Documents\Python\cubicweb\cubicweb\bin
  C:\Program Files\Graphviz2.24\bin

The PYTHONPATH variable should also contain::

  C:\Documents and Settings\Jane\My Documents\Python\cubicweb\

From now, on a fresh `cmd` shell, you should be able to type::

  cubicweb-ctl list

... and get a meaningful output.

233
234
235
236
Running an instance as a service
--------------------------------

This currently assumes that the instances configurations is located
237
at C:\\etc\\cubicweb.d.
238

Aurelien Campeas's avatar
Aurelien Campeas committed
239
For a cube 'my_cube', you will then find C:\\etc\\cubicweb.d\\my_cube\\win32svc.py
240
241
242
243
244
245
246
247
248
249
that has to be used thusly::

  win32svc install

This should just register your instance as a windows service. A simple::

  net start cubicweb-my_cube

should start the service.

250

Nicolas Chauvat's avatar
Nicolas Chauvat committed
251
252
PostgreSQL installation
```````````````````````
253

Nicolas Chauvat's avatar
Nicolas Chauvat committed
254
Please refer to the `PostgreSQL project online documentation`_.
255

Nicolas Chauvat's avatar
Nicolas Chauvat committed
256
.. _`PostgreSQL project online documentation`: http://www.postgresql.org/
257

Nicolas Chauvat's avatar
Nicolas Chauvat committed
258
259
You need to install the three following packages: `postgresql-8.3`,
`postgresql-contrib-8.3` and `postgresql-plpython-8.3`.
260
261


Nicolas Chauvat's avatar
Nicolas Chauvat committed
262
263
264
265
Other dependencies
``````````````````

You can also install:
266
267
268
269
270
271
272
273
274
275
276
277
278

* `pyro` if you wish the repository to be accessible through Pyro
  or if the client and the server are not running on the same machine
  (in which case the packages will have to be installed on both
  machines)

* `python-ldap` if you plan to use a LDAP source on the server

.. _ConfigurationEnv:

Environment configuration
-------------------------

Nicolas Chauvat's avatar
Nicolas Chauvat committed
279
If you installed *CubicWeb* by cloning the Mercurial forest, then you
Nicolas Chauvat's avatar
Nicolas Chauvat committed
280
will need to update the environment variable PYTHONPATH by adding
281
282
283
284
the path to the forest ``cubicweb``:

Add the following lines to either `.bashrc` or `.bash_profile` to configure
your development environment ::
Nicolas Chauvat's avatar
Nicolas Chauvat committed
285

Nicolas Chauvat's avatar
Nicolas Chauvat committed
286
    export PYTHONPATH=/full/path/to/cubicweb-forest
287

Nicolas Chauvat's avatar
Nicolas Chauvat committed
288
If you installed *CubicWeb* with packages, no configuration is required and your
289
new cubes will be placed in `/usr/share/cubicweb/cubes` and your instances
Nicolas Chauvat's avatar
Nicolas Chauvat committed
290
will be placed in `/etc/cubicweb.d`.
291

Nicolas Chauvat's avatar
Nicolas Chauvat committed
292
293
You may run a system-wide install of *CubicWeb* in "user mode" and use it for
development by setting the following environment variable::
294

Nicolas Chauvat's avatar
Nicolas Chauvat committed
295
    export CW_MODE=user
296
    export CW_CUBES_PATH=~/lib/cubes
Nicolas Chauvat's avatar
Nicolas Chauvat committed
297
298
299
    export CW_INSTANCES_DIR=~/etc/cubicweb.d/
    export CW_INSTANCES_DATA_DIR=$CW_INSTANCES_DIR
    export CW_RUNTIME_DIR=/tmp
300
301
302
303
304
305
306

.. note::
    The values given above are our suggestions but of course
    can be different.


Databases configuration
Sandrine Ribeau's avatar
Sandrine Ribeau committed
307
308
-----------------------

Nicolas Chauvat's avatar
Nicolas Chauvat committed
309
.. _ConfigurationPostgresql:
310

Nicolas Chauvat's avatar
Nicolas Chauvat committed
311
312
PostgreSQL configuration
````````````````````````
313
314

.. note::
Nicolas Chauvat's avatar
Nicolas Chauvat committed
315
    If you already have an existing cluster and PostgreSQL server
316
    running, you do not need to execute the initilization step
Nicolas Chauvat's avatar
Nicolas Chauvat committed
317
    of your PostgreSQL database.
318

Nicolas Chauvat's avatar
Nicolas Chauvat committed
319
* First, initialize the database PostgreSQL with the command ``initdb``.
320
321
322
323
  ::

    $ initdb -D /path/to/pgsql

Nicolas Chauvat's avatar
Nicolas Chauvat committed
324
  Once initialized, start the database server PostgreSQL
325
  with the command::
Nicolas Chauvat's avatar
Nicolas Chauvat committed
326

327
328
329
330
331
    $ postgres -D /path/to/psql

  If you cannot execute this command due to permission issues, please
  make sure that your username has write access on the database.
  ::
Nicolas Chauvat's avatar
Nicolas Chauvat committed
332

333
334
335
    $ chown username /path/to/pgsql

* The database authentication can be either set to `ident sameuser`
Nicolas Chauvat's avatar
Nicolas Chauvat committed
336
  or `md5`.
337
338
339
340
341
  If set to `md5`, make sure to use an existing user
  of your database.
  If set to `ident sameuser`, make sure that your
  client's operating system user name has a matching user in
  the database. If not, please do as follow to create a user::
Nicolas Chauvat's avatar
Nicolas Chauvat committed
342

343
344
345
346
347
    $ su
    $ su - postgres
    $ createuser -s -P username

  The option `-P` (for password prompt), will encrypt the password with
Nicolas Chauvat's avatar
Nicolas Chauvat committed
348
  the method set in the configuration file ``pg_hba.conf``.
349
350
  If you do not use this option `-P`, then the default value will be null
  and you will need to set it with::
Nicolas Chauvat's avatar
Nicolas Chauvat committed
351

352
353
354
355
    $ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql"

  This login/password will be requested when you will create an
  instance with `cubicweb-ctl create` to initialize the database of
356
  your instance.
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372

.. note::
    The authentication method can be configured in ``pg_hba.conf``.


.. FIXME Are these steps really necessary? It seemed to work without.

* Installation of plain-text index extension ::

    cat /usr/share/postgresql/8.3/contrib/tsearch2.sql | psql -U username template1

* Installation of plpythonu language by default ::

    createlang -U pgadmin plpythonu template1

MySql configuration
Sandrine Ribeau's avatar
Sandrine Ribeau committed
373
```````````````````
374
Yout must add the following lines in ``/etc/mysql/my.cnf`` file::
375

376
    transaction-isolation=READ-COMMITTED
377
378
379
380
    default-storage-engine=INNODB
    default-character-set=utf8
    max_allowed_packet = 128M

381
382
383
384
.. note::
    It is unclear whether mysql supports indexed string of arbitrary lenght or
    not.

385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
SQLServer configuration
-----------------------

As of this writing, sqlserver support is in progress. You should be
able to connect, create a database and go quite far, but some of the
generated SQL is still currently not accepted by the backend.

The `source` configuration file may look like this (specific parts
only are shown)::

  [system]
  db-driver=sqlserver2005
  db-user=someuser
  # database password not needed
  #db-password=toto123
  #db-create/init may ask for a pwd: just say anything
  db-extra-arguments=Trusted_Connection
  db-encoding=utf8


405
406
407
408
409
410
411
412
413
414
415
416
417
Pyro configuration
------------------

If you use Pyro, it is required to have a name server Pyro running on your
network (by default it is detected by a broadcast request).

To do so, you need to :

* launch the server manually before starting cubicweb as a server with
  `pyro-nsd start`

* edit the file ``/etc/default/pyro-nsd`` so that the name server pyro
  will be launched automatically when the machine fire up
Adrien Di Mascio's avatar
Adrien Di Mascio committed
418