|
1 .. -*- coding: utf-8 -*- |
|
2 |
|
3 .. _ConfigEnv: |
|
4 |
|
5 Set-up of a *CubicWeb* environment |
|
6 ================================== |
|
7 |
|
8 You can `configure the database`_ system of your choice: |
|
9 |
|
10 - `PostgreSQL configuration`_ |
|
11 - `MySql configuration`_ |
|
12 - `SQLServer configuration`_ |
|
13 - `SQLite configuration`_ |
|
14 |
|
15 For advenced features you can have a look to: |
|
16 |
|
17 - `Pyro configuration`_ |
|
18 - `Cubicweb resources configuration`_ |
|
19 |
|
20 .. _`configure the database`: DatabaseInstallation_ |
|
21 .. _`PostgreSQL configuration`: PostgresqlConfiguration_ |
|
22 .. _`MySql configuration`: MySqlConfiguration_ |
|
23 .. _`SQLServer configuration`: SQLServerConfiguration_ |
|
24 .. _`SQLite configuration`: SQLiteConfiguration_ |
|
25 .. _`Pyro configuration`: PyroConfiguration_ |
|
26 .. _`Cubicweb resources configuration`: RessourcesConfiguration_ |
|
27 |
|
28 |
|
29 |
|
30 .. _RessourcesConfiguration: |
|
31 |
|
32 Cubicweb resources configuration |
|
33 -------------------------------- |
|
34 |
|
35 .. autodocstring:: cubicweb.cwconfig |
|
36 |
|
37 |
|
38 .. _DatabaseInstallation: |
|
39 |
|
40 Databases configuration |
|
41 ----------------------- |
|
42 |
|
43 Each instance can be configured with its own database connection information, |
|
44 that will be stored in the instance's :file:`sources` file. The database to use |
|
45 will be chosen when creating the instance. Currently cubicweb has been tested |
|
46 using Postgresql (recommended), MySQL, SQLServer and SQLite. |
|
47 |
|
48 Other possible sources of data include CubicWeb, Subversion, LDAP and Mercurial, |
|
49 but at least one relational database is required for CubicWeb to work. You do |
|
50 not need to install a backend that you do not intend to use for one of your |
|
51 instances. SQLite is not fit for production use, but it works well for testing |
|
52 and ships with Python, which saves installation time when you want to get |
|
53 started quickly. |
|
54 |
|
55 .. _PostgresqlConfiguration: |
|
56 |
|
57 PostgreSQL |
|
58 ~~~~~~~~~~ |
|
59 |
|
60 For installation, please refer to the `PostgreSQL project online documentation`_. |
|
61 |
|
62 .. _`PostgreSQL project online documentation`: http://www.postgresql.org/ |
|
63 |
|
64 You need to install the three following packages: `postgresql-8.X`, |
|
65 `postgresql-client-8.X`, and `postgresql-plpython-8.X`. If you run postgres |
|
66 version prior to 8.3, you'll also need the `postgresql-contrib-8.X` package for |
|
67 full-text search extension. |
|
68 |
|
69 If you run postgres on another host than the |cubicweb| repository, you should |
|
70 install the `postgresql-client` package on the |cubicweb| host, and others on the |
|
71 database host. |
|
72 |
|
73 .. Note:: |
|
74 |
|
75 If you already have an existing cluster and PostgreSQL server running, you do |
|
76 not need to execute the initilization step of your PostgreSQL database unless |
|
77 you want a specific cluster for |cubicweb| databases or if your existing |
|
78 cluster doesn't use the UTF8 encoding (see note below). |
|
79 |
|
80 * First, initialize a PostgreSQL cluster with the command ``initdb``. |
|
81 :: |
|
82 |
|
83 $ initdb -E UTF8 -D /path/to/pgsql |
|
84 |
|
85 Notice the encoding specification. This is necessary since |cubicweb| usually |
|
86 want UTF8 encoded database. If you use a cluster with the wrong encoding, you'll |
|
87 get error like:: |
|
88 |
|
89 new encoding (UTF8) is incompatible with the encoding of the template database (SQL_ASCII) |
|
90 HINT: Use the same encoding as in the template database, or use template0 as template. |
|
91 |
|
92 |
|
93 Once initialized, start the database server PostgreSQL with the command:: |
|
94 |
|
95 $ postgres -D /path/to/psql |
|
96 |
|
97 If you cannot execute this command due to permission issues, please make sure |
|
98 that your username has write access on the database. :: |
|
99 |
|
100 $ chown username /path/to/pgsql |
|
101 |
|
102 * The database authentication can be either set to `ident sameuser` or `md5`. If |
|
103 set to `md5`, make sure to use an existing user of your database. If set to |
|
104 `ident sameuser`, make sure that your client's operating system user name has a |
|
105 matching user in the database. If not, please do as follow to create a user:: |
|
106 |
|
107 $ su |
|
108 $ su - postgres |
|
109 $ createuser -s -P username |
|
110 |
|
111 The option `-P` (for password prompt), will encrypt the password with the |
|
112 method set in the configuration file :file:`pg_hba.conf`. If you do not use this |
|
113 option `-P`, then the default value will be null and you will need to set it |
|
114 with:: |
|
115 |
|
116 $ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql" |
|
117 |
|
118 .. Note:: |
|
119 The authentication method can be configured in file:`pg_hba.conf`. |
|
120 |
|
121 |
|
122 The above login/password will be requested when you will create an instance with |
|
123 `cubicweb-ctl create` to initialize the database of your instance. |
|
124 |
|
125 Notice that the `cubicweb-ctl db-create` does database initialization that |
|
126 may requires a postgres superuser. That's why a login/password is explicitly asked |
|
127 at this step, so you can use there a superuser without using this user when running |
|
128 the instance. Things that require special privileges at this step: |
|
129 |
|
130 * database creation, require the 'create database' permission |
|
131 * install the plpython extension language (require superuser) |
|
132 * install the tsearch extension for postgres version prior to 8.3 (require superuser) |
|
133 |
|
134 To avoid using a super user each time you create an install, a nice trick is to |
|
135 install plpython (and tsearch when needed) on the special `template1` database, |
|
136 so they will be installed automatically when cubicweb databases are created |
|
137 without even with needs for special access rights. To do so, run :: |
|
138 |
|
139 # Installation of plpythonu language by default :: |
|
140 $ createlang -U pgadmin plpythonu template1 |
|
141 $ psql -U pgadmin template1 |
|
142 template1=# update pg_language set lanpltrusted=TRUE where lanname='plpythonu'; |
|
143 |
|
144 Where `pgadmin` is a postgres superuser. The last command is necessary since by |
|
145 default plpython is an 'untrusted' language and as such can't be used by non |
|
146 superuser. This update fix that problem by making it trusted. |
|
147 |
|
148 To install the tsearch plain-text index extension on postgres prior to 8.3, run:: |
|
149 |
|
150 cat /usr/share/postgresql/8.X/contrib/tsearch2.sql | psql -U username template1 |
|
151 |
|
152 |
|
153 |
|
154 .. _MySqlConfiguration: |
|
155 |
|
156 MySql |
|
157 ~~~~~ |
|
158 |
|
159 You must add the following lines in ``/etc/mysql/my.cnf`` file:: |
|
160 |
|
161 transaction-isolation=READ-COMMITTED |
|
162 default-storage-engine=INNODB |
|
163 default-character-set=utf8 |
|
164 max_allowed_packet = 128M |
|
165 |
|
166 .. Note:: |
|
167 It is unclear whether mysql supports indexed string of arbitrary length or |
|
168 not. |
|
169 |
|
170 |
|
171 .. _SQLServerConfiguration: |
|
172 |
|
173 SQLServer |
|
174 ~~~~~~~~~ |
|
175 |
|
176 As of this writing, support for SQLServer 2005 is functional but incomplete. You |
|
177 should be able to connect, create a database and go quite far, but some of the |
|
178 SQL generated from RQL queries is still currently not accepted by the |
|
179 backend. Porting to SQLServer 2008 is also an item on the backlog. |
|
180 |
|
181 The `source` configuration file may look like this (specific parts only are |
|
182 shown):: |
|
183 |
|
184 [system] |
|
185 db-driver=sqlserver2005 |
|
186 db-user=someuser |
|
187 # database password not needed |
|
188 #db-password=toto123 |
|
189 #db-create/init may ask for a pwd: just say anything |
|
190 db-extra-arguments=Trusted_Connection |
|
191 db-encoding=utf8 |
|
192 |
|
193 |
|
194 |
|
195 .. _SQLiteConfiguration: |
|
196 |
|
197 SQLite |
|
198 ~~~~~~ |
|
199 SQLite has the great advantage of requiring almost no configuration. Simply |
|
200 use 'sqlite' as db-driver, and set path to the dabase as db-name. Don't specify |
|
201 anything for db-user and db-password, they will be ignore anyway. |
|
202 |
|
203 .. Note:: |
|
204 SQLite is great for testing and to play with cubicweb but is not suited for |
|
205 production environments. |
|
206 |
|
207 |
|
208 .. _PyroConfiguration: |
|
209 |
|
210 Pyro configuration |
|
211 ------------------ |
|
212 |
|
213 If you want to use Pyro to access your instance remotely, or to have multi-source |
|
214 or distributed configuration, it is required to have a Pyro name server running |
|
215 on your network. By default it is detected by a broadcast request, but you can |
|
216 specify a location in the instance's configuration file. |
|
217 |
|
218 To do so, you need to : |
|
219 |
|
220 * launch the pyro name server with `pyro-nsd start` before starting cubicweb |
|
221 |
|
222 * under debian, edit the file :file:`/etc/default/pyro-nsd` so that the name |
|
223 server pyro will be launched automatically when the machine fire up |
|
224 |
|
225 |