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