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

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
12
13
14
|cubicweb| is packaged for `Debian and Ubuntu`_, is `pip installable`_ and
`easy_install installable`_. It can be installed from source using a tarball_
or the `Mercurial version control system`_ . Windows user may want to check the
`Windows Installation`_ section.
15

Sylvain Thénault's avatar
Sylvain Thénault committed
16
17
Also, since version 3.9, can be safely installed, used and contained inside a
`virtualenv`_.
18
19
20
21
22
23
24
25
26
27
28
29


.. _`Debian and Ubuntu` : DebianInstallation_
.. _`pip installable`: PipInstallation_
.. _`easy_install installable`: EasyInstallInstallation_
.. _tarball: TarballInstallation_
.. _`Mercurial version control system`: MercurialInstallation_
.. _`Windows Installation`: WindowsInstallation_
.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv


.. file:///home/pyves/tmp/cwdoc/html/admin/setup.html#pipinstallation
30

31
32
33
34
35
.. _DebianInstallation:

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

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

39
For Debian Squeeze (stable)::
40

41
  deb http://download.logilab.org/production/ squeeze/
42

43
For Debian Sid (unstable)::
44

45
  deb http://download.logilab.org/production/ sid/
46

47
For Ubuntu Lucid (Long Term Support)::
48

49
  deb http://download.logilab.org/production/ lucid/
50
51
52
53


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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
54
  apt-get update
Sylvain Thénault's avatar
Sylvain Thénault committed
55
  apt-get install cubicweb cubicweb-dev
56
57


58
59
60
61
`cubicweb` installs the framework itself, allowing you to create new instances.

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

63
64
65
.. note::

   `cubicweb-dev` will install basic sqlite support. You can easily setup
66
   `cubicweb with other database`_ using the following virtual packages :
67
68
69
70
   `cubicweb-postgresql-support` contains necessary dependency for using
   `cubicweb with postgresql datatabase`_ and `cubicweb-mysql-support` contains
   necessary dependency for using `cubicweb with mysql database`_ .

71
72
There is also a wide variety of :ref:`cubes <AvailableCubes>` listed on the
`CubicWeb.org Forge`_ available as debian packages and tarball.
73
74
75

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

Aurelien Campeas's avatar
Aurelien Campeas committed
77
1. become root using sudo
78
2. download http://download.logilab.org/logilab-dists-key.asc using e.g. wget
79
80
81
3. run "apt-key add logilab-dists-key.asc"
4. re-run apt-get update (manually or through the package manager, whichever you prefer)

82
.. _`Logilab's gnupg key`: http://download.logilab.org/logilab-dists-key.asc
83
.. _`CubicWeb.org Forge`: http://www.cubicweb.org/project/
84
85
86
.. _`cubicweb with other database`: DatabaseInstallation_
.. _`cubicweb with postgresql datatabase` : PostgresqlConfiguration_
.. _`cubicweb with mysql database` : MySqlConfiguration_
87

88

89
90
91
92
93
.. _PipInstallation:

Installation with pip
`````````````````````

94
95
96
97
pip_ is a smart python utility that lets you automatically download, build,
install, and manage python packages and their dependencies.

|cubicweb| and its cubes have been pip_ installable since version 3.9. Search
98
99
100
for them on pypi_::

  pip install cubicweb
101
102
103
104
105
106
107
108
109
110
111
112
113
114
  pip install cubicweb-blog

.. note::

    Pip is the recommended way to install |cubicweb| if there is no binary
    package available on your system or you want to install it inside a
    `virtualenv`_. However pip doesn't install binary package and may require
    several compilation steps while installing |cubicweb| dependencies. If you
    don't have a compilation environment you should use  `easy_install
    installation`_ to install |cubicweb|.

    Once, |cubicweb| is installed, this limitation doesn't apply when installing
    cubes.

115
116
117

.. _pip: http://pypi.python.org/pypi/pip
.. _pypi: http://pypi.python.org/pypi?%3Aaction=search&term=cubicweb
118
.. _`easy_install installation`: EasyInstallInstallation_
119

Adrien Chauve's avatar
Adrien Chauve committed
120

121
122
.. warning::

123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
  |cubicweb| depends upon the `lxml` python module. This module contains ``C``
  code that must be compiled.  To successfully install |cubicweb| with pip, you
  must either have an environment ables to compile Python ``C`` extensions or
  preinstall lxml from a binary package.

.. note::

  For better performance the setup processor will compile a ``C`` extension for
  the :ref:`RQL <RQL>` language if you have an environment ables to compile
  Python ``C`` extensions and the `gecode library`_.  Otherwise, a pure python
  alternative will be used for degraded performance.

.. _`gecode library`: http://www.gecode.org/
.. _`easy_install`:   http://packages.python.org/distribute/easy_install.html


.. _EasyInstallInstallation:

Installation with EasyInstall
``````````````````````````````

.. note::

    We don't recommend the use of `easy_install` and setuptools in the generic
    case. However as easy_install is currently the sole pure python package
    system that support binary installation. Using `easy_install` is currently
    the easiest way to install |cubicweb| when you don't have a compilation
    environment set-up or Debian based distribution.


|cubicweb| is easy_install_ installable for version 3.9::

  easy_install cubicweb

.. warning::

    Cubes are **not** is easy_install_ installable. But they are
    `pip installable`_




.. _SourceInstallation:
166

167
168
169
Install from source
```````````````````

170
171
.. _TarballInstallation:

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

174
  http://download.logilab.org/pub/cubicweb/
175

176
.. _`download site`: http://download.logilab.org/pub/cubicweb/
177

Nicolas Chauvat's avatar
Nicolas Chauvat committed
178
Make sure you also have all the :ref:`InstallDependencies`.
179

180
.. _MercurialInstallation:
181

182
183
184
Install from version control system
```````````````````````````````````

185
You can keep up to date with on-going development by using Mercurial::
186

187
  hg clone http://hg.logilab.org/cubicweb
188
189

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

191
192
193
194
195
196
197
198
199
200
201
202
A practical way to get many of CubicWeb's dependencies and a nice set
of base cubes is to run the `clone_deps.py` script located in
`cubicweb/bin/`::

  python cubicweb/bin/clone_deps.py

(Windows users should replace slashes with antislashes).

This script will clone a set of mercurial repositories into in the
directory containing the CubicWeb repository, and update them to the
latest published version tag (if any).

Aurelien Campeas's avatar
Aurelien Campeas committed
203
204
205
206
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.
207

208
209
210
211
212
213
214
215
216
Even better, `hg tags` will display a list of tags in reverse
chronological order. One reasonnable way to get to a working version
is to pick the latest published version (as done by the `clone_deps`
script). These look like `cubicweb-debian-version-3.9.7-1`. Typing::

 hg update cubicweb-debian-version-3.9.7-1

will update the repository files to this version.

Nicolas Chauvat's avatar
Nicolas Chauvat committed
217
Make sure you also have all the :ref:`InstallDependencies`.
218

219

Adrien Chauve's avatar
Adrien Chauve committed
220
221
.. _WindowsInstallation:

222
223
224
Windows installation
````````````````````

225
226
227
228
Your best option is probably the :ref:`PipInstallation`. If it does not work or
if you want more control over the process, continue with the following
instructions.

229
Base elements
230
~~~~~~~~~~~~~
231

232
233
234
235
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.
236

237
You should start by downloading and installing Python version >= 2.5 and < 3.
238

239
240
241
242
243
An alternative option would be installing the Python(x,y)
distribution. Python(x,y) is not a requirement, but it makes things easier for
Windows user by wrapping in a single installer python 2.5 plus numerous useful
third-party modules and applications (including Eclipse + pydev, which is an
arguably good IDE for Python under Windows). Download it from this page::
244

245
  http://code.google.com/p/pythonxy/wiki/Downloads
246

247
248
Then you must grab Twisted. There is a windows installer directly available from
this page::
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266

  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

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

269
270
A windows compiled recent version of gettext::

271
  http://download.logilab.org/pub/gettext/gettext-0.17-win32-setup.exe
272
273
274
275

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

276
  http://download.logilab.org/pub/rql/rql-0.23.0.win32-py2.5.exe
277

278
Pyro enables remote access to cubicweb repository instances. Get it there::
Aurelien Campeas's avatar
Aurelien Campeas committed
279
280
281

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

282
283
284
285
286
287
288
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.

289
290
Having graphviz will allow schema drawings, which is quite recommended (albeit
not mandatory). You should get an msi installer there::
291
292
293

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

294
Simplejson is needed when installing with Python 2.5, but included in the
295
standard library for Python >= 2.6. Get it from there::
296
297
298

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
299
300
301
Make sure you also have all the :ref:`InstallDependencies` that are not specific
to Windows.

302
Tools
303
~~~~~
304

305
306
Get mercurial + its standard windows GUI (TortoiseHG) there (the latest is the
greatest)::
307
308
309

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

310
311
If you need to peruse mercurial over ssh, it can be helpful to get an ssh client
like Putty::
312
313
314
315
316
317
318
319

  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/

320
321
Getting the sources
~~~~~~~~~~~~~~~~~~~
322

323
324
325
326
You can either download the latest release (see
:ref:`SourceInstallation`) or get the development version using
Mercurial (see :ref:`MercurialInstallation` and below), which is more
convenient.
327
328

Environment variables
329
~~~~~~~~~~~~~~~~~~~~~
330

331
332
333
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).
334

335
336
337
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.
338

339
340
341
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::
342
343
344
345
346
347
348
349
350
351
352
353
354
355

  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.

356
Running an instance as a service
357
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
358

359
360
This currently assumes that the instances configurations is located at
C:\\etc\\cubicweb.d.
361

362
For a cube 'my_instance', you will then find
363
C:\\etc\\cubicweb.d\\my_instance\\win32svc.py that has to be used as follows::
364
365
366
367
368

  win32svc install

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

369
  net start cubicweb-my_instance
370
371
372

should start the service.

373

Nicolas Chauvat's avatar
Nicolas Chauvat committed
374
375
376
377
Other dependencies
``````````````````

You can also install:
378
379
380
381
382
383
384
385
386

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


387
.. _DatabaseInstallation:
388

389
390
Databases configuration
-----------------------
391

392
393
394
395
Each instance can be configured with its own database connection information,
that will be stored in the instance's :file:`sources` file. The database to use
will be chosen when creating the instance. Currently cubicweb has been tested
using Postgresql (recommended), MySQL, SQLServer and SQLite.
396
397

Other possible sources of data include CubicWeb, Subversion, LDAP and Mercurial,
398
399
400
401
402
but at least one relational database is required for CubicWeb to work. You do
not need to install a backend that you do not intend to use for one of your
instances. SQLite is not fit for production use, but it works well for testing
and ships with Python, which saves installation time when you want to get
started quickly.
Nicolas Chauvat's avatar
Nicolas Chauvat committed
403

404
.. _PostgresqlConfiguration:
405

406
407
PostgreSQL configuration
````````````````````````
408

409
For installation, please refer to the `PostgreSQL project online documentation`_.
410

411
.. _`PostgreSQL project online documentation`: http://www.postgresql.org/
412

413
414
415
416
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.
417

418
419
420
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.
421

422
.. Note::
Sandrine Ribeau's avatar
Sandrine Ribeau committed
423

424
425
426
427
    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).
428

429
430
* First, initialize a PostgreSQL cluster with the command ``initdb``.
  ::
431

432
    $ initdb -E UTF8 -D /path/to/pgsql
433

434
435
436
437
438
439
  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.
440
441


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

444
445
    $ postgres -D /path/to/psql

446
447
  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
448

449
450
    $ chown username /path/to/pgsql

451
452
453
454
* 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
455

456
457
458
459
    $ su
    $ su - postgres
    $ createuser -s -P username

460
461
462
463
  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
464

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

467
468
469
470
471
472
.. 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.
473

474
475
476
477
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:
478

479
480
481
* 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)
482

483
484
485
486
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 ::
487

488
489
490
491
  # 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';
492

493
494
495
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.
496

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

499
500
501
502
    cat /usr/share/postgresql/8.X/contrib/tsearch2.sql | psql -U username template1


.. _MySqlConfiguration:
503
504

MySql configuration
Sandrine Ribeau's avatar
Sandrine Ribeau committed
505
```````````````````
506
You must add the following lines in ``/etc/mysql/my.cnf`` file::
507

508
    transaction-isolation=READ-COMMITTED
509
510
511
512
    default-storage-engine=INNODB
    default-character-set=utf8
    max_allowed_packet = 128M

513
.. Note::
514
    It is unclear whether mysql supports indexed string of arbitrary length or
515
516
    not.

517
518
519

.. _SQLServerConfiguration:

520
SQLServer configuration
521
```````````````````````
522

523
524
525
526
As of this writing, support for SQLServer 2005 is functional but incomplete. You
should be able to connect, create a database and go quite far, but some of the
SQL generated from RQL queries is still currently not accepted by the
backend. Porting to SQLServer 2008 is also an item on the backlog.
527

528
529
The `source` configuration file may look like this (specific parts only are
shown)::
530
531
532
533
534
535
536
537
538
539
540

  [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


541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556

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

557
558
559
Pyro configuration
------------------

560
If you want to use Pyro to access your instance remotely, or to have multi-source
561
562
or distributed configuration, it is required to have a Pyro name server running
on your network. By default it is detected by a broadcast request, but you can
563
specify a location in the instance's configuration file.
564
565
566

To do so, you need to :

567
* launch the pyro name server with `pyro-nsd start` before starting cubicweb
568
569
570
571
572
573
574
575
576

* 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