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

62
63
64
65
66
67
68
69
70
71
72
73
74
.. _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
75
76
.. _SourceInstallation:

77
78
79
80
81
82
.. warning::

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

83
84
85
86
87
88
89
90
91
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
92
Make sure you also have all the :ref:`InstallDependencies`.
93

94
.. _MercurialInstallation:
95

96
97
98
Install from version control system
```````````````````````````````````

99
You can keep up to date with on-going development by using Mercurial::
100

101
  hg clone http://www.logilab.org/hg/forests/cubicweb
102
103

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

105
106
107
108
109
110
111
112
113
114
115
116
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
117
118
119
120
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.
121

122
123
124
125
126
127
128
129
130
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
131
Make sure you also have all the :ref:`InstallDependencies`.
132

133

Adrien Chauve's avatar
Adrien Chauve committed
134
135
.. _WindowsInstallation:

136
137
138
Windows installation
````````````````````

139
140
141
142
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.

143
Base elements
144
~~~~~~~~~~~~~
145

146
147
148
149
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.
150

151
You should start by downloading and installing Python version >= 2.5 and < 3.
152

153
154
155
156
157
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::
158

159
  http://code.google.com/p/pythonxy/wiki/Downloads
160

161
162
Then you must grab Twisted. There is a windows installer directly available from
this page::
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180

  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

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

183
184
185
186
187
188
189
190
191
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

192
Pyro enables remote access to cubicweb repository instances. Get it there::
Aurelien Campeas's avatar
Aurelien Campeas committed
193
194
195

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

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

203
204
Having graphviz will allow schema drawings, which is quite recommended (albeit
not mandatory). You should get an msi installer there::
205
206
207

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

208
Simplejson is needed when installing with Python 2.5, but included in the
209
standard library for Python >= 2.6. Get it from there::
210
211
212

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

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

216
Tools
217
~~~~~
218

219
220
Get mercurial + its standard windows GUI (TortoiseHG) there (the latest is the
greatest)::
221
222
223

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

224
225
If you need to peruse mercurial over ssh, it can be helpful to get an ssh client
like Putty::
226
227
228
229
230
231
232
233

  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/

234
235
Getting the sources
~~~~~~~~~~~~~~~~~~~
236

237
238
239
240
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.
241
242

Environment variables
243
~~~~~~~~~~~~~~~~~~~~~
244

245
246
247
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).
248

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

253
254
255
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::
256
257
258
259
260
261
262
263
264
265
266
267
268
269

  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.

270
Running an instance as a service
271
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
272

273
274
This currently assumes that the instances configurations is located at
C:\\etc\\cubicweb.d.
275

276
For a cube 'my_instance', you will then find
277
C:\\etc\\cubicweb.d\\my_instance\\win32svc.py that has to be used as follows::
278
279
280
281
282

  win32svc install

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

283
  net start cubicweb-my_instance
284
285
286

should start the service.

287

Nicolas Chauvat's avatar
Nicolas Chauvat committed
288
289
290
291
Other dependencies
``````````````````

You can also install:
292
293
294
295
296
297
298
299
300

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


301
.. _DatabaseInstallation:
302

303
304
Databases configuration
-----------------------
305

306
307
308
309
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.
310
311

Other possible sources of data include CubicWeb, Subversion, LDAP and Mercurial,
312
313
314
315
316
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
317

318
.. _PostgresqlConfiguration:
319

320
321
PostgreSQL configuration
````````````````````````
322

323
For installation, please refer to the `PostgreSQL project online documentation`_.
324

325
.. _`PostgreSQL project online documentation`: http://www.postgresql.org/
326

327
328
329
330
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.
331

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

336
.. Note::
Sandrine Ribeau's avatar
Sandrine Ribeau committed
337

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

343
344
* First, initialize a PostgreSQL cluster with the command ``initdb``.
  ::
345

346
    $ initdb -E UTF8 -D /path/to/pgsql
347

348
349
350
351
352
353
  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.
354
355


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

358
359
    $ postgres -D /path/to/psql

360
361
  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
362

363
364
    $ chown username /path/to/pgsql

365
366
367
368
* 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
369

370
371
372
373
    $ su
    $ su - postgres
    $ createuser -s -P username

374
375
376
377
  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
378

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

381
382
383
384
385
386
.. 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.
387

388
389
390
391
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:
392

393
394
395
* 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)
396

397
398
399
400
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 ::
401

402
403
404
405
  # 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';
406

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

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

413
414
415
416
    cat /usr/share/postgresql/8.X/contrib/tsearch2.sql | psql -U username template1


.. _MySqlConfiguration:
417
418

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

422
    transaction-isolation=READ-COMMITTED
423
424
425
426
    default-storage-engine=INNODB
    default-character-set=utf8
    max_allowed_packet = 128M

427
.. Note::
428
    It is unclear whether mysql supports indexed string of arbitrary length or
429
430
    not.

431
432
433

.. _SQLServerConfiguration:

434
SQLServer configuration
435
```````````````````````
436

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

442
443
The `source` configuration file may look like this (specific parts only are
shown)::
444
445
446
447
448
449
450
451
452
453
454

  [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


455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470

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

471
472
473
Pyro configuration
------------------

474
If you want to use Pyro to access your instance remotly, or to have multi-source
475
476
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
477
specify a location in the instance's configuration file.
478
479
480

To do so, you need to :

481
* launch the pyro name server with `pyro-nsd start` before starting cubicweb
482
483
484
485
486
487
488
489
490

* 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