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

9
10
11
12
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
Installation of `Cubicweb` and its dependencies
-----------------------------------------------

`CubicWeb` is packaged for Debian and Ubuntu, but can be installed from source
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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
  apt-get install cubicweb cubicweb-dev

`cubicweb` installs the framework itself, allowing you to create
new applications.

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


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.

Postgres installation
`````````````````````

Please refer to the `Postgresql project online documentation`_.

.. _`Postgresql project online documentation`: http://www.postgresql.org/

You need to install the three following packages: `postgres-8.3`,
`postgres-contrib-8.3` and `postgresql-plpython-8.3`.


Then you can install:

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

If you installed `CubicWeb` by cloning the Mercurial forest, then you
Nicolas Chauvat's avatar
Nicolas Chauvat committed
92
will need to update the environment variable PYTHONPATH by adding
93
94
95
96
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
97

98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
  export PYTHONPATH=/full/path/to/cubicweb-forest

If you installed the debian packages, no configuration is required.
Your new cubes will be placed in `/usr/share/cubicweb/cubes` and
your applications will be placed in `/etc/cubicweb.d`.

To use others directories then you will have to configure the
following environment variables as follows::

    export CW_CUBES_PATH=~/lib/cubes
    export CW_REGISTRY=~/etc/cubicweb.d/
    export CW_INSTANCE_DATA=$CW_REGISTRY
    export CW_RUNTIME=/tmp

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


Databases configuration
Sandrine Ribeau's avatar
Sandrine Ribeau committed
118
119
-----------------------

120
121
122
123
124


.. _ConfigurationPostgres:

Postgres configuration
Sandrine Ribeau's avatar
Sandrine Ribeau committed
125
``````````````````````
126
127
128
129
130
131
132
133
134
135
136

.. note::
    If you already have an existing cluster and postgres server
    running, you do not need to execute the initilization step
    of your Postgres database.

* First, initialize the database Postgres with the command ``initdb``.
  ::

    $ initdb -D /path/to/pgsql

Nicolas Chauvat's avatar
Nicolas Chauvat committed
137
  Once initialized, start the database server Postgres
138
  with the command::
Nicolas Chauvat's avatar
Nicolas Chauvat committed
139

140
141
142
143
144
    $ 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
145

146
147
148
    $ chown username /path/to/pgsql

* The database authentication can be either set to `ident sameuser`
Nicolas Chauvat's avatar
Nicolas Chauvat committed
149
  or `md5`.
150
151
152
153
154
  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
155

156
157
158
159
160
    $ 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
161
  the method set in the configuration file ``pg_hba.conf``.
162
163
  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
164

165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
    $ 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
  your application.

.. 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
186
```````````````````
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
Yout must add the following lines in /etc/mysql/my.cnf file::

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

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
207