setup.rst 6.71 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
===================================================
Nicolas Chauvat's avatar
Nicolas Chauvat committed
6
Installation and set-up of a *CubicWeb* environment
7
===================================================
Adrien Di Mascio's avatar
Adrien Di Mascio committed
8

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
12
*CubicWeb* is packaged for Debian and Ubuntu, but can be installed from source
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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
38
  apt-get update
39
40
41
  apt-get install cubicweb cubicweb-dev

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

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

49
The repositories are signed with `Logilab's gnupg key`_. To avoid warning on "apt-get update":
Aurelien Campeas's avatar
Aurelien Campeas committed
50
1. become root using sudo
51
52
53
54
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)

55
.. _`Logilab's gnupg key`: http://ftp.logilab.org/dists/logilab-dists-key.asc
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

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/

or keep up to date with on-going development by using Mercurial and its forest
extension::

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

See :ref:`MercurialPresentation` for more details about Mercurial.
Aurelien Campeas's avatar
Aurelien Campeas committed
72
73
74
75
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.
76

77
78
79
In both cases, make sure you have installed the dependencies (see appendixes for
the list).

Nicolas Chauvat's avatar
Nicolas Chauvat committed
80
81
PostgreSQL installation
```````````````````````
82

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

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
87
88
You need to install the three following packages: `postgresql-8.3`,
`postgresql-contrib-8.3` and `postgresql-plpython-8.3`.
89
90


Nicolas Chauvat's avatar
Nicolas Chauvat committed
91
92
93
94
Other dependencies
``````````````````

You can also install:
95
96
97
98
99
100
101
102
103
104
105
106
107

* `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
108
If you installed *CubicWeb* by cloning the Mercurial forest, then you
Nicolas Chauvat's avatar
Nicolas Chauvat committed
109
will need to update the environment variable PYTHONPATH by adding
110
111
112
113
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
114

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

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

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
124
    export CW_MODE=user
125
    export CW_CUBES_PATH=~/lib/cubes
Nicolas Chauvat's avatar
Nicolas Chauvat committed
126
127
128
    export CW_INSTANCES_DIR=~/etc/cubicweb.d/
    export CW_INSTANCES_DATA_DIR=$CW_INSTANCES_DIR
    export CW_RUNTIME_DIR=/tmp
129
130
131
132
133
134
135

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


Databases configuration
Sandrine Ribeau's avatar
Sandrine Ribeau committed
136
137
-----------------------

138
139


Nicolas Chauvat's avatar
Nicolas Chauvat committed
140
.. _ConfigurationPostgresql:
141

Nicolas Chauvat's avatar
Nicolas Chauvat committed
142
143
PostgreSQL configuration
````````````````````````
144
145

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
150
* First, initialize the database PostgreSQL with the command ``initdb``.
151
152
153
154
  ::

    $ initdb -D /path/to/pgsql

Nicolas Chauvat's avatar
Nicolas Chauvat committed
155
  Once initialized, start the database server PostgreSQL
156
  with the command::
Nicolas Chauvat's avatar
Nicolas Chauvat committed
157

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

164
165
166
    $ chown username /path/to/pgsql

* The database authentication can be either set to `ident sameuser`
Nicolas Chauvat's avatar
Nicolas Chauvat committed
167
  or `md5`.
168
169
170
171
172
  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
173

174
175
176
177
178
    $ 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
179
  the method set in the configuration file ``pg_hba.conf``.
180
181
  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
182

183
184
185
186
    $ 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
187
  your instance.
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203

.. 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
204
```````````````````
205
Yout must add the following lines in ``/etc/mysql/my.cnf`` file::
206
207
208
209
210
211

    transaction-isolation = READ-COMMITTED
    default-storage-engine=INNODB
    default-character-set=utf8
    max_allowed_packet = 128M

212
213
214
215
.. note::
    It is unclear whether mysql supports indexed string of arbitrary lenght or
    not.

216
217
218
219
220
221
222
223
224
225
226
227
228
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
229