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