Commit 2e1ca3ee authored by Alain Leufroy's avatar Alain Leufroy
Browse files

[doc] major update of the install documentation

branch : stable
parent a4a115aab086
.. -*- coding: utf-8 -*-
.. _ConfigEnv:
Set-up of a *CubicWeb* environment
You can `configure the database`_ system of your choice:
- `PostgreSQL configuration`_
- `MySql configuration`_
- `SQLServer configuration`_
- `SQLite configuration`_
For advenced features you can have a look to:
- `Pyro configuration`_
- `Cubicweb resources configuration`_
.. _`configure the database`: DatabaseInstallation_
.. _`PostgreSQL configuration`: PostgresqlConfiguration_
.. _`MySql configuration`: MySqlConfiguration_
.. _`SQLServer configuration`: SQLServerConfiguration_
.. _`SQLite configuration`: SQLiteConfiguration_
.. _`Pyro configuration`: PyroConfiguration_
.. _`Cubicweb resources configuration`: RessourcesConfiguration_
.. _RessourcesConfiguration:
Cubicweb resources configuration
.. autodocstring:: cubicweb.cwconfig
.. _DatabaseInstallation:
Databases configuration
Each instance can be configured with its own database connection information,
that will be stored in the instance's :file:`sources` file. The database to use
will be chosen when creating the instance. Currently cubicweb has been tested
using Postgresql (recommended), MySQL, SQLServer and SQLite.
Other possible sources of data include CubicWeb, Subversion, LDAP and Mercurial,
but at least one relational database is required for CubicWeb to work. You do
not need to install a backend that you do not intend to use for one of your
instances. SQLite is not fit for production use, but it works well for testing
and ships with Python, which saves installation time when you want to get
started quickly.
.. _PostgresqlConfiguration:
For installation, please refer to the `PostgreSQL project online documentation`_.
.. _`PostgreSQL project online documentation`:
You need to install the three following packages: `postgresql-8.X`,
`postgresql-client-8.X`, and `postgresql-plpython-8.X`. If you run postgres
version prior to 8.3, you'll also need the `postgresql-contrib-8.X` package for
full-text search extension.
If you run postgres on another host than the |cubicweb| repository, you should
install the `postgresql-client` package on the |cubicweb| host, and others on the
database host.
.. Note::
If you already have an existing cluster and PostgreSQL server running, you do
not need to execute the initilization step of your PostgreSQL database unless
you want a specific cluster for |cubicweb| databases or if your existing
cluster doesn't use the UTF8 encoding (see note below).
* First, initialize a PostgreSQL cluster with the command ``initdb``.
$ initdb -E UTF8 -D /path/to/pgsql
Notice the encoding specification. This is necessary since |cubicweb| usually
want UTF8 encoded database. If you use a cluster with the wrong encoding, you'll
get error like::
new encoding (UTF8) is incompatible with the encoding of the template database (SQL_ASCII)
HINT: Use the same encoding as in the template database, or use template0 as template.
Once initialized, start the database server PostgreSQL with the command::
$ 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. ::
$ chown username /path/to/pgsql
* The database authentication can be either set to `ident sameuser` or `md5`. 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::
$ su
$ su - postgres
$ createuser -s -P username
The option `-P` (for password prompt), will encrypt the password with the
method set in the configuration file :file:`pg_hba.conf`. If you do not use this
option `-P`, then the default value will be null and you will need to set it
$ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql"
.. Note::
The authentication method can be configured in file:`pg_hba.conf`.
The above login/password will be requested when you will create an instance with
`cubicweb-ctl create` to initialize the database of your instance.
Notice that the `cubicweb-ctl db-create` does database initialization that
may requires a postgres superuser. That's why a login/password is explicitly asked
at this step, so you can use there a superuser without using this user when running
the instance. Things that require special privileges at this step:
* database creation, require the 'create database' permission
* install the plpython extension language (require superuser)
* install the tsearch extension for postgres version prior to 8.3 (require superuser)
To avoid using a super user each time you create an install, a nice trick is to
install plpython (and tsearch when needed) on the special `template1` database,
so they will be installed automatically when cubicweb databases are created
without even with needs for special access rights. To do so, run ::
# Installation of plpythonu language by default ::
$ createlang -U pgadmin plpythonu template1
$ psql -U pgadmin template1
template1=# update pg_language set lanpltrusted=TRUE where lanname='plpythonu';
Where `pgadmin` is a postgres superuser. The last command is necessary since by
default plpython is an 'untrusted' language and as such can't be used by non
superuser. This update fix that problem by making it trusted.
To install the tsearch plain-text index extension on postgres prior to 8.3, run::
cat /usr/share/postgresql/8.X/contrib/tsearch2.sql | psql -U username template1
.. _MySqlConfiguration:
You must add the following lines in ``/etc/mysql/my.cnf`` file::
max_allowed_packet = 128M
.. Note::
It is unclear whether mysql supports indexed string of arbitrary length or
.. _SQLServerConfiguration:
As of this writing, support for SQLServer 2005 is functional but incomplete. You
should be able to connect, create a database and go quite far, but some of the
SQL generated from RQL queries is still currently not accepted by the
backend. Porting to SQLServer 2008 is also an item on the backlog.
The `source` configuration file may look like this (specific parts only are
# database password not needed
#db-create/init may ask for a pwd: just say anything
.. _SQLiteConfiguration:
SQLite has the great advantage of requiring almost no configuration. Simply
use 'sqlite' as db-driver, and set path to the dabase as db-name. Don't specify
anything for db-user and db-password, they will be ignore anyway.
.. Note::
SQLite is great for testing and to play with cubicweb but is not suited for
production environments.
.. _PyroConfiguration:
Pyro configuration
If you want to use Pyro to access your instance remotely, or to have multi-source
or distributed configuration, it is required to have a Pyro name server running
on your network. By default it is detected by a broadcast request, but you can
specify a location in the instance's configuration file.
To do so, you need to :
* launch the pyro name server with `pyro-nsd start` before starting cubicweb
* under debian, edit the file :file:`/etc/default/pyro-nsd` so that the name
server pyro will be launched automatically when the machine fire up
......@@ -4,11 +4,6 @@
Configure an instance
On a Unix system, the instances are usually stored in the directory
:file:`/etc/cubicweb.d/`. During development, the
:file:`~/etc/cubicweb.d/` directory is looked up, as well as the paths
in :envvar:`CW_INSTANCES_DIR` environment variable.
While creating an instance, a configuration file is generated in::
$ (CW_INSTANCES_DIR) / <instance> / <configuration name>.conf
.. -*- coding: utf-8 -*-
.. _SetUpWindowsEnv:
Installing a development environement on Windows
Setting up a Windows development environment is not too complicated
but it requires a series of small steps.
We proposed an example of a typical |cubicweb| installation on Windows
from sources. We assume everything goes into ``C:\\`` and for any
package, without version specification, "the latest is
the greatest".
Take into the mind that adjusting the installation drive should be
Install the required elements
|cubicweb| requires some base elements that must be installed to run
correctly. So, first of all, you must install them :
* python >= 2.5 and < 3
(`Download Python <>`_).
You can also consider the Python(x,y) distribution
(`Download Python(x,y) <>`_)
as it makes things easier for Windows user by wrapping in a single installer
python 2.5 plus numerous useful third-party modules and
applications (including Eclipse + pydev, which is an arguably good
IDE for Python under Windows).
* `Twisted <>`_ is an event-driven
networking engine
(`Download Twisted <>`_)
* `lxml <>`_ library
(version >=2.2.1) allows working with XML and HTML
(`Download lxml <>`_)
* `Postgresql 8.4 <>`_,
an object-relational database system
(`Download Postgresql <>`_)
and its python drivers
(`Download psycopg <>`_)
* A recent version of `gettext`
(`Download gettext <>`_).
* `rql <>`_,
the recent version of the Relationship Query Language parser
(`Download rql <>`_).
Install optional elements
We recommend you to install the following elements. They are not
mandatory but they activate very interesting features in |cubicweb|:
* `Simplejson <>`_
must be installed if you have python <= 2.5
(`Download simplejson <>`_).
It is included in the Standard library from Python >= 2.6.
* `Pyro <>`_
enables remote access to cubicweb repository instances.
It also allows the client and the server not running on the same machine
(`Download Pyro <>`_).
* `python-ldap <>`_
provides access to LDAP/Active directory directories
(`Download python-ldap <>`_).
* `graphviz <>`_
which allow schema drawings.
(`Download graphviz <>`_).
It is quite recommended (albeit not mandatory).
Other elements will activate more features once installed. Take a look
at :ref:`InstallDependencies`.
Useful tools
Some additional tools could be useful to develop :ref:`cubes <AvailableCubes>`
with the framework.
* `mercurial <>`_ and its standard
windows GUI (`TortoiseHG <>`_)
allow you to get the source code of |cubicweb| from control version
repositories. So you will be able to get the latest development
version in an easy way
(`Download mercurial <>`_).
* You can also consider the ssh client `Putty` in order to peruse
mercurial over ssh (`Download <>`_).
* If you are an Eclipse user, mercurial can be integrated using the
`MercurialEclipse` plugin
(`Home page <>`_).
Getting the sources
There are tow ways to get the sources of |cubicweb| and its
:ref:`cubes <AvailableCubes>`:
* download the latest release (:ref:`SourceInstallation`)
* get the development version using Mercurial
Environment variables
You will need some convenience environment variables once all is set up. These
variables are settable through the GUI by getting at the `System properties`
window (by righ-clicking on `My Computer` -> `properties`).
In the `advanced` tab, there is an `Environment variables` button. Click on
it. That opens a small window allowing edition of user-related and system-wide
We will consider only user variables. First, the ``PATH`` variable. Assuming
you are logged as user *Jane*, add the following paths, separated by
C:\Documents and Settings\Jane\My Documents\Python\cubicweb\cubicweb\bin
C:\Program Files\Graphviz2.24\bin
The ``PYTHONPATH`` variable should also contain::
C:\Documents and Settings\Jane\My Documents\Python\cubicweb\
From now, on a fresh `cmd` shell, you should be able to type::
cubicweb-ctl list
... and get a meaningful output.
Running an instance as a service
This currently assumes that the instances configurations is located at
``C:\\etc\\cubicweb.d``. For a cube 'my_instance', you will find
Now, register your instance as a windows service with::
win32svc install
Then start the service with::
net start cubicweb-my_instance
This diff is collapsed.
......@@ -38,7 +38,7 @@ The unbeliever will read the :ref:`Tutorials`.
The hacker will join development at the forge_.
The impatient developer will move right away to :ref:`SetUpEnv`.
The impatient developer will move right away to :ref:`SetUpEnv` then to :ref:`ConfigEnv`.
The chatter lover will join the `jabber forum`_, the `mailing-list`_ and the blog_.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment