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