setup.rst 16.3 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
52
53
54
.. note::

   `cubicweb-dev` will install basic sqlite support. You can easily setup
   `cubicweb with other database`_ with the following virtual packages :
   `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`_ .

55
56
57
58
59
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":
60

Aurelien Campeas's avatar
Aurelien Campeas committed
61
1. become root using sudo
62
63
64
65
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)

66
.. _`Logilab's gnupg key`: http://ftp.logilab.org/dists/logilab-dists-key.asc
67
.. _`CubicWeb.org Forge`: http://www.cubicweb.org/project/
68
69
70
.. _`cubicweb with other database`: DatabaseInstallation_
.. _`cubicweb with postgresql datatabase` : PostgresqlConfiguration_
.. _`cubicweb with mysql database` : MySqlConfiguration_
71

72

73
74
75
76
77
78
79
80
81
82
83
84
85
.. _PipInstallation:

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

|cubicweb| and its cubes have been pip_ installable since version 3.8. Search
for them on pypi_::

  pip install cubicweb

.. _pip: http://pypi.python.org/pypi/pip
.. _pypi: http://pypi.python.org/pypi?%3Aaction=search&term=cubicweb

Adrien Chauve's avatar
Adrien Chauve committed
86
87
.. _SourceInstallation:

88
89
90
91
92
93
.. warning::

  This method may still have hiccups. If it does not work for you,
  please consider installing from version control system
  (:ref:`MercurialInstallation`).

94
95
96
97
98
99
100
101
102
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/

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

105
.. _MercurialInstallation:
106

107
108
109
Install from version control system
```````````````````````````````````

110
You can keep up to date with on-going development by using Mercurial::
111

112
  hg clone http://hg.logilab.org/cubicweb
113
114

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

116
117
118
119
120
121
122
123
124
125
126
127
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
128
129
130
131
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.
132

133
134
135
136
137
138
139
140
141
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
142
Make sure you also have all the :ref:`InstallDependencies`.
143

144

Adrien Chauve's avatar
Adrien Chauve committed
145
146
.. _WindowsInstallation:

147
148
149
Windows installation
````````````````````

150
151
152
153
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.

154
Base elements
155
~~~~~~~~~~~~~
156

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

162
You should start by downloading and installing Python version >= 2.5 and < 3.
163

164
165
166
167
168
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::
169

170
  http://code.google.com/p/pythonxy/wiki/Downloads
171

172
173
Then you must grab Twisted. There is a windows installer directly available from
this page::
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191

  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

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

194
195
196
197
198
199
200
201
202
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

203
Pyro enables remote access to cubicweb repository instances. Get it there::
Aurelien Campeas's avatar
Aurelien Campeas committed
204
205
206

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

207
208
209
210
211
212
213
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.

214
215
Having graphviz will allow schema drawings, which is quite recommended (albeit
not mandatory). You should get an msi installer there::
216
217
218

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

219
Simplejson is needed when installing with Python 2.5, but included in the
220
standard library for Python >= 2.6. Get it from there::
221
222
223

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

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

227
Tools
228
~~~~~
229

230
231
Get mercurial + its standard windows GUI (TortoiseHG) there (the latest is the
greatest)::
232
233
234

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

235
236
If you need to peruse mercurial over ssh, it can be helpful to get an ssh client
like Putty::
237
238
239
240
241
242
243
244

  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/

245
246
Getting the sources
~~~~~~~~~~~~~~~~~~~
247

248
249
250
251
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.
252
253

Environment variables
254
~~~~~~~~~~~~~~~~~~~~~
255

256
257
258
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).
259

260
261
262
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.
263

264
265
266
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::
267
268
269
270
271
272
273
274
275
276
277
278
279
280

  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.

281
Running an instance as a service
282
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
283

284
285
This currently assumes that the instances configurations is located at
C:\\etc\\cubicweb.d.
286

287
For a cube 'my_instance', you will then find
288
C:\\etc\\cubicweb.d\\my_instance\\win32svc.py that has to be used as follows::
289
290
291
292
293

  win32svc install

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

294
  net start cubicweb-my_instance
295
296
297

should start the service.

298

Nicolas Chauvat's avatar
Nicolas Chauvat committed
299
300
301
302
Other dependencies
``````````````````

You can also install:
303
304
305
306
307
308
309
310
311

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


312
.. _DatabaseInstallation:
313

314
315
Databases configuration
-----------------------
316

317
318
319
320
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.
321
322

Other possible sources of data include CubicWeb, Subversion, LDAP and Mercurial,
323
324
325
326
327
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
328

329
.. _PostgresqlConfiguration:
330

331
332
PostgreSQL configuration
````````````````````````
333

334
For installation, please refer to the `PostgreSQL project online documentation`_.
335

336
.. _`PostgreSQL project online documentation`: http://www.postgresql.org/
337

338
339
340
341
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.
342

343
344
345
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.
346

347
.. Note::
Sandrine Ribeau's avatar
Sandrine Ribeau committed
348

349
350
351
352
    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).
353

354
355
* First, initialize a PostgreSQL cluster with the command ``initdb``.
  ::
356

357
    $ initdb -E UTF8 -D /path/to/pgsql
358

359
360
361
362
363
364
  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.
365
366


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

369
370
    $ postgres -D /path/to/psql

371
372
  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
373

374
375
    $ chown username /path/to/pgsql

376
377
378
379
* 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
380

381
382
383
384
    $ su
    $ su - postgres
    $ createuser -s -P username

385
386
387
388
  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
389

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

392
393
394
395
396
397
.. 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.
398

399
400
401
402
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:
403

404
405
406
* 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)
407

408
409
410
411
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 ::
412

413
414
415
416
  # 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';
417

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

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

424
425
426
427
    cat /usr/share/postgresql/8.X/contrib/tsearch2.sql | psql -U username template1


.. _MySqlConfiguration:
428
429

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

433
    transaction-isolation=READ-COMMITTED
434
435
436
437
    default-storage-engine=INNODB
    default-character-set=utf8
    max_allowed_packet = 128M

438
.. Note::
439
    It is unclear whether mysql supports indexed string of arbitrary length or
440
441
    not.

442
443
444

.. _SQLServerConfiguration:

445
SQLServer configuration
446
```````````````````````
447

448
449
450
451
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.
452

453
454
The `source` configuration file may look like this (specific parts only are
shown)::
455
456
457
458
459
460
461
462
463
464
465

  [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


466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481

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

482
483
484
Pyro configuration
------------------

485
If you want to use Pyro to access your instance remotly, or to have multi-source
486
487
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
488
specify a location in the instance's configuration file.
489
490
491

To do so, you need to :

492
* launch the pyro name server with `pyro-nsd start` before starting cubicweb
493
494
495
496
497
498
499
500
501

* 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