setup.rst 14.5 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
-----------------------------------------------

11
|cubicweb| is packaged for Debian and Ubuntu, but can be installed from source
12
13
using a tarball or the Mercurial version control system.

14

15
16
17
18
19
.. _DebianInstallation:

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

20
21
Depending on the distribution you are using, add the appropriate line to your
list of sources (for example by editing ``/etc/apt/sources.list``).
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

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
38
  apt-get update
39
40
41
  apt-get install cubicweb cubicweb-dev


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

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

47
48
49
50
51
There is also a wide variety of cubes listed on the `CubicWeb.org Forge`_
available as debian packages and tarball.

The repositories are signed with `Logilab's gnupg key`_. To avoid warning on
"apt-get update":
52

Aurelien Campeas's avatar
Aurelien Campeas committed
53
1. become root using sudo
54
55
56
57
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)

58
.. _`Logilab's gnupg key`: http://ftp.logilab.org/dists/logilab-dists-key.asc
59
60
.. _`CubicWeb.org Forge`: http://www.cubicweb.org/project/

61

Adrien Chauve's avatar
Adrien Chauve committed
62
63
.. _SourceInstallation:

64
65
66
67
68
69
70
71
72
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/

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

75
76
77
78
79
|cubicweb| should soon be pip_ installable, stay tuned (expected in 3.8).

.. _pip: http://pypi.python.org/pypi/pip


80
81
82
83
84
Install from version control system
```````````````````````````````````

You can keep up to date with on-going development by using Mercurial and its
forest extension::
85
86
87
88

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

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

Aurelien Campeas's avatar
Aurelien Campeas committed
90
91
92
93
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.
94

95
96
97
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).
98

99

Adrien Chauve's avatar
Adrien Chauve committed
100
101
.. _WindowsInstallation:

102
103
104
105
Windows installation
````````````````````

Base elements
106
~~~~~~~~~~~~~
107

108
109
110
111
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.
112

113
114
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::
115
116
117

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

118
119
120
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).
121

122
123
Then you must grab Twisted. There is a windows installer directly available from
this page::
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

  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

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

144
145
146
147
148
149
150
151
152
A windows compiled recent version of gettext::

  http://ftp.logilab.org/pub/gettext/gettext-0.17-win32-setup.exe

A pre-compiled version of rql for windows (take care of retrieving the
most recent version available there)::

  http://ftp.logilab.org/pub/rql/rql-0.23.0.win32-py2.5.exe

153
Pyro enables remote access to cubicweb repository instances. Get it there::
Aurelien Campeas's avatar
Aurelien Campeas committed
154
155
156

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

157
158
159
160
161
162
163
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.

164
165
Having graphviz will allow schema drawings, which is quite recommended (albeit
not mandatory). You should get an msi installer there::
166
167
168

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

169
170
Simplejson will be provided within the forest, but a win32 compiled version will
run much faster::
171
172
173

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

174
Tools
175
~~~~~
176

177
178
Get mercurial + its standard windows GUI (TortoiseHG) there (the latest is the
greatest)::
179
180
181

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

182
183
If you need to peruse mercurial over ssh, it can be helpful to get an ssh client
like Putty::
184
185
186
187
188
189
190
191
192

  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
193
~~~~~~~~~~~~~~~~~~~~~~
194

195
You need to enable the mercurial forest extension. To do this, edit the file::
196
197
198
199
200
201
202
203

  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
204
205
Eclipse. From the IDE, choose File -> Import. In the box, select `Mercurial/Clone
repository using MercurialEclipse`.
206
207
208
209
210
211
212

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.

213
214
215
216
217
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.
218
219

Environment variables
220
~~~~~~~~~~~~~~~~~~~~~
221

222
223
224
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).
225

226
227
228
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.
229

230
231
232
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::
233
234
235
236
237
238
239
240
241
242
243
244
245
246

  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.

247
Running an instance as a service
248
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
249

250
251
This currently assumes that the instances configurations is located at
C:\\etc\\cubicweb.d.
252

253
254
For a cube 'my_cube', you will then find
C:\\etc\\cubicweb.d\\my_cube\\win32svc.py that has to be used thusly::
255
256
257
258
259
260
261
262
263

  win32svc install

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

  net start cubicweb-my_cube

should start the service.

264

Nicolas Chauvat's avatar
Nicolas Chauvat committed
265
266
267
268
Other dependencies
``````````````````

You can also install:
269
270
271
272
273
274
275
276
277

* `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


278
.. _DatabaseInstallation:
279

280
281
Databases configuration
-----------------------
282

283
284
285
Whatever the backend used, database connection information are stored in the
instance's :file:`sources` file. Currently cubicweb has been tested using
Postgresql (recommanded), MySQL, SQLServer and SQLite.
Nicolas Chauvat's avatar
Nicolas Chauvat committed
286

287
.. _PostgresqlConfiguration:
288

289
290
PostgreSQL configuration
````````````````````````
291

292
For installation, please refer to the `PostgreSQL project online documentation`_.
293

294
.. _`PostgreSQL project online documentation`: http://www.postgresql.org/
295

296
297
298
299
You need to install the three following packages: `postgresql-8.X`,
`postgresql-client-8.X`, and `postgresql-plpython-8.X`. If you run postgres
version prior to 8.3, you'll also need the `postgresql-contrib-8.X` package for
full-text search extension.
300

301
302
303
If you run postgres on another host than the |cubicweb| repository, you should
install the `postgresql-client` package on the |cubicweb| host, and others on the
database host.
304

305
.. Note::
Sandrine Ribeau's avatar
Sandrine Ribeau committed
306

307
308
309
310
    If you already have an existing cluster and PostgreSQL server running, you do
    not need to execute the initilization step of your PostgreSQL database unless
    you want a specific cluster for |cubicweb| databases or if your existing
    cluster doesn't use the UTF8 encoding (see note below).
311

312
313
* First, initialize a PostgreSQL cluster with the command ``initdb``.
  ::
314

315
    $ initdb -E UTF8 -D /path/to/pgsql
316

317
318
319
320
321
322
  Notice the encoding specification. This is necessary since |cubicweb| usually
  want UTF8 encoded database. If you use a cluster with the wrong encoding, you'll
  get error like::

    new encoding (UTF8) is incompatible with the encoding of the template database (SQL_ASCII)
    HINT:  Use the same encoding as in the template database, or use template0 as template.
323
324


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

327
328
    $ postgres -D /path/to/psql

329
330
  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
331

332
333
    $ chown username /path/to/pgsql

334
335
336
337
* The database authentication can be either set to `ident sameuser` or `md5`.  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
338

339
340
341
342
    $ su
    $ su - postgres
    $ createuser -s -P username

343
344
345
346
  The option `-P` (for password prompt), will encrypt the password with the
  method set in the configuration file :file:`pg_hba.conf`.  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
347

348
349
    $ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql"

350
351
352
353
354
355
.. Note::
    The authentication method can be configured in file:`pg_hba.conf`.


The above login/password will be requested when you will create an instance with
`cubicweb-ctl create` to initialize the database of your instance.
356

357
358
359
360
Notice that the `cubicweb-ctl db-create` does database initialization that
may requires a postgres superuser. That's why a login/password is explicitly asked
at this step, so you can use there a superuser without using this user when running
the instance. Things that require special privileges at this step:
361

362
363
364
* database creation, require the 'create database' permission
* install the plpython extension language (require superuser)
* install the tsearch extension for postgres version prior to 8.3 (require superuser)
365

366
367
368
369
To avoid using a super user each time you create an install, a nice trick is to
install plpython (and tsearch when needed) on the special `template1` database,
so they will be installed automatically when cubicweb databases are created
without even with needs for special access rights. To do so, run ::
370

371
372
373
374
  # Installation of plpythonu language by default ::
  $ createlang -U pgadmin plpythonu template1
  $ psql -U pgadmin template1
  template1=# update pg_language set lanpltrusted=TRUE where lanname='plpythonu';
375

376
377
378
Where `pgadmin` is a postgres superuser. The last command is necessary since by
default plpython is an 'untrusted' language and as such can't be used by non
superuser. This update fix that problem by making it trusted.
379

380
To install the tsearch plain-text index extension on postgres prior to 8.3, run::
381

382
383
384
385
    cat /usr/share/postgresql/8.X/contrib/tsearch2.sql | psql -U username template1


.. _MySqlConfiguration:
386
387

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

391
    transaction-isolation=READ-COMMITTED
392
393
394
395
    default-storage-engine=INNODB
    default-character-set=utf8
    max_allowed_packet = 128M

396
.. Note::
397
398
399
    It is unclear whether mysql supports indexed string of arbitrary lenght or
    not.

400
401
402

.. _SQLServerConfiguration:

403
SQLServer configuration
404
```````````````````````
405

406
407
408
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.
409

410
411
The `source` configuration file may look like this (specific parts only are
shown)::
412
413
414
415
416
417
418
419
420
421
422

  [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


423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438

.. _SQLiteConfiguration:

SQLite configuration
````````````````````
SQLite has the great advantage of requiring almost no configuration. Simply
use 'sqlite' as db-driver, and set path to the dabase as db-name. Don't specify
anything for db-user and db-password, they will be ignore anyway.

.. Note::
  SQLite is great for testing and to play with cubicweb but is not suited for
  production environments.


.. _PyroConfiguration:

439
440
441
Pyro configuration
------------------

442
443
444
445
If you want to use Pyro to access your instance remotly, or to have multi-source
or distributed configuration, it is required to have a name server Pyro running
on your network. By by default it is detected by a broadcast request, but you can
specify a location in the instance's configuration file.
446
447
448

To do so, you need to :

449
450
451
452
453
454
455
456
457
458
459
* launch the server manually before starting cubicweb as a server with `pyro-nsd
  start`

* under debian, edit the file :file:`/etc/default/pyro-nsd` so that the name
  server pyro will be launched automatically when the machine fire up


Cubicweb resources configuration
--------------------------------

.. autodocstring:: cubicweb.cwconfig