[doc] major update of the install documentation stable
authorAlain Leufroy <alain.leufroy@logilab.fr>
Wed, 06 Apr 2011 12:33:39 +0200
branchstable
changeset 7226 e88c57c10b34
parent 7225 a4a115aab086
child 7230 edd2a575a8e7
[doc] major update of the install documentation
doc/book/en/admin/config.rst
doc/book/en/admin/instance-config.rst
doc/book/en/admin/setup-windows.rst
doc/book/en/admin/setup.rst
doc/book/en/index.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/admin/config.rst	Wed Apr 06 12:33:39 2011 +0200
@@ -0,0 +1,225 @@
+.. -*- 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:
+
+PostgreSQL
+~~~~~~~~~~
+
+For installation, please refer to the `PostgreSQL project online documentation`_.
+
+.. _`PostgreSQL project online documentation`: http://www.postgresql.org/
+
+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
+  with::
+
+    $ 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:
+
+MySql
+~~~~~
+
+You must add the following lines in ``/etc/mysql/my.cnf`` file::
+
+    transaction-isolation=READ-COMMITTED
+    default-storage-engine=INNODB
+    default-character-set=utf8
+    max_allowed_packet = 128M
+
+.. Note::
+    It is unclear whether mysql supports indexed string of arbitrary length or
+    not.
+
+
+.. _SQLServerConfiguration:
+
+SQLServer
+~~~~~~~~~
+
+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
+shown)::
+
+  [system]
+  db-driver=sqlserver2005
+  db-user=someuser
+  # database password not needed
+  #db-password=toto123
+  #db-create/init may ask for a pwd: just say anything
+  db-extra-arguments=Trusted_Connection
+  db-encoding=utf8
+
+
+
+.. _SQLiteConfiguration:
+
+SQLite
+~~~~~~
+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
+
+
--- a/doc/book/en/admin/instance-config.rst	Thu Apr 14 11:36:47 2011 +0200
+++ b/doc/book/en/admin/instance-config.rst	Wed Apr 06 12:33:39 2011 +0200
@@ -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
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/admin/setup-windows.rst	Wed Apr 06 12:33:39 2011 +0200
@@ -0,0 +1,156 @@
+.. -*- 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
+straightforward.
+
+
+
+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 <http://www.python.org/download/>`_). 
+  You can also consider the Python(x,y) distribution 
+  (`Download Python(x,y) <http://code.google.com/p/pythonxy/wiki/Downloads>`_)
+  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 <http://twistedmatrix.com/trac/>`_ is an event-driven
+  networking engine 
+  (`Download Twisted <http://twistedmatrix.com/trac/>`_)
+
+* `lxml <http://codespeak.net/lxml/>`_ library
+  (version >=2.2.1) allows working with XML and HTML 
+  (`Download lxml <http://pypi.python.org/pypi/lxml/2.2.1>`_)
+
+* `Postgresql 8.4 <http://www.postgresql.org/>`_, 
+  an object-relational database system 
+  (`Download Postgresql <http://www.enterprisedb.com/products/pgdownload.do#windows>`_) 
+  and its python drivers 
+  (`Download psycopg <http://www.stickpeople.com/projects/python/win-psycopg/#Version2>`_)
+
+* A recent version of `gettext` 
+  (`Download gettext <http://download.logilab.org/pub/gettext/gettext-0.17-win32-setup.exe>`_).
+
+* `rql <http://www.logilab.org/project/rql>`_, 
+  the recent version of the Relationship Query Language parser 
+  (`Download rql <http://download.logilab.org/pub/rql/rql-0.26.3.win32-py2.5.exe>`_).
+
+Install optional elements
+-------------------------
+
+We recommend you to install the following elements. They are not
+mandatory but they activate very interesting features in |cubicweb|:
+
+* `Simplejson <http://pypi.python.org/pypi/simplejson/>`_ 
+  must be installed if you have python <= 2.5 
+  (`Download simplejson <http://www.osuch.org/python-simplejson%3Awin32>`_).
+  It is included in the Standard library from Python >= 2.6.
+
+* `Pyro <http://www.xs4all.nl/~irmen/pyro3/>`_ 
+  enables remote access to cubicweb repository instances.
+  It also allows the client and the server not running on the same machine
+  (`Download Pyro <http://www.xs4all.nl/~irmen/pyro3/download/>`_).
+
+* `python-ldap <http://pypi.python.org/pypi/python-ldap>`_ 
+  provides access to LDAP/Active directory directories
+  (`Download python-ldap <http://www.osuch.org/python-ldap>`_).
+
+* `graphviz <http://www.graphviz.org/>`_ 
+  which allow schema drawings.  
+  (`Download graphviz <http://www.graphviz.org/Download_windows.php>`_).
+  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 <http://mercurial.selenic.com/>`_ and its standard
+  windows GUI (`TortoiseHG <http://tortoisehg.bitbucket.org/>`_) 
+  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 <http://bitbucket.org/tortoisehg/stable/wiki/download>`_).
+
+* You can also consider the ssh client `Putty` in order to peruse
+  mercurial over ssh (`Download <http://www.putty.org/>`_).
+
+* If you are an Eclipse user, mercurial can be integrated using the
+  `MercurialEclipse` plugin 
+  (`Home page <http://www.vectrace.com/mercurialeclipse/>`_).
+
+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 
+  (:ref:`MercurialInstallation`)
+
+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
+variables.
+
+We will consider only user variables. First, the ``PATH`` variable. Assuming 
+you are logged as user *Jane*, add the following paths, separated by 
+semi-colons::
+
+  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
+``C:\\etc\\cubicweb.d\\my_instance\\win32svc.py``.
+
+Now, register your instance as a windows service with::
+
+  win32svc install
+
+Then start the service with::
+
+  net start cubicweb-my_instance
--- a/doc/book/en/admin/setup.rst	Thu Apr 14 11:36:47 2011 +0200
+++ b/doc/book/en/admin/setup.rst	Wed Apr 06 12:33:39 2011 +0200
@@ -2,39 +2,57 @@
 
 .. _SetUpEnv:
 
-Installation and set-up of a |cubicweb| environment
-===================================================
+Installation of a *CubicWeb* environment
+========================================
+
+There are different simple ways to install |cubicweb| and its
+dependencies depending on your requirements:
 
-Installation of `Cubicweb` and its dependencies
------------------------------------------------
+* `Distribution-specific installation`. This option shows you how to
+  easily install |cubicweb| and its requirements on your system:
 
-|cubicweb| is packaged for `Debian and Ubuntu`_, is `pip installable`_ and
-`easy_install installable`_. It can be installed from source using a tarball_
-or the `Mercurial version control system`_ . Windows user may want to check the
-`Windows Installation`_ section.
+  - `Installation on Debian/Ubuntu`_ 
+  - `Installation on Windows`_
+  - `Install in a virtualenv`_
+
+* `Official release installation`. This options is the best approach
+  for those who want a flexible and up-to-date stable
+  version. |cubicweb| is published on `PyPI`_:
 
-Also, since version 3.9, can be safely installed, used and contained inside a
-`virtualenv`_.
+  - `Installation with pip`_
+  - `Installation with easy_install`_
 
+* `Lastest development version installation`. This option is
+  dedicated for power-users who want the very lastest
+  features (|cubicweb| is an `Agile software <http://en.wikipedia.org/wiki/Agile_software_development>`_).
+
+  - `Installation from tarball`_
+  - `Installation from version control`_
 
-.. _`Debian and Ubuntu` : DebianInstallation_
-.. _`pip installable`: PipInstallation_
-.. _`easy_install installable`: EasyInstallInstallation_
-.. _tarball: TarballInstallation_
-.. _`Mercurial version control system`: MercurialInstallation_
-.. _`Windows Installation`: WindowsInstallation_
-.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
+Once installed, you can have a look to :ref:`ConfigEnv` for better control
+and advanced features of |cubicweb|.
 
+.. _`Installation on Debian/Ubuntu`: DebianInstallation_
+.. _`Installation on Windows`: WindowsInstallation_
+.. _`Install in a virtualenv`: VirtualenvInstallation_
+.. _`Installation with pip`: PipInstallation_
+.. _`Installation with easy_install`: EasyInstallInstallation_
+.. _`Installation from tarball`: TarballInstallation_
+.. _`Installation from version control`: MercurialInstallation_
 
-.. file:///home/pyves/tmp/cwdoc/html/admin/setup.html#pipinstallation
 
 .. _DebianInstallation:
 
-Debian and Ubuntu packages
-```````````````````````````
+Debian/Ubuntu install
+---------------------
+
+|cubicweb| is packaged for Debian/Ubuntu (and derived
+distributions). Their integrated package-management systems make
+installation and upgrading much easier for users since
+dependencies/recommends (like databases) are automatically installed.
 
 Depending on the distribution you are using, add the appropriate line to your
-list of sources (for example by editing ``/etc/apt/sources.list``).
+`list of sources` (for example by editing ``/etc/apt/sources.list``).
 
 For Debian Squeeze (stable)::
 
@@ -44,151 +62,187 @@
 
   deb http://download.logilab.org/production/ sid/
 
-For Ubuntu Lucid (Long Term Support)::
+For Ubuntu Lucid (Long Term Support) and newer::
 
   deb http://download.logilab.org/production/ lucid/
 
+  Note that for Ubuntu Maverick and newer, you shall use the `lucid`
+  repository and install the ``libgecode19`` package from `lucid
+  universe <http://packages.ubuntu.com/lucid/libgecode19>`_.
 
-You can now install the required packages with the following command::
+The repositories are signed with the `Logilab's gnupg key`_. You can download
+and register the key to avoid warnings::
+
+  wget -q http://download.logilab.org/logilab-dists-key.asc -O- | sudo apt-key add -
+
+Update your list of packages and perform the installation::
 
   apt-get update
   apt-get install cubicweb cubicweb-dev
 
-
-`cubicweb` installs the framework itself, allowing you to create new instances.
+``cubicweb`` installs the framework itself, allowing you to create new
+instances. ``cubicweb-dev`` installs the development environment
+allowing you to develop new cubes.
 
-`cubicweb-dev` installs the development environment allowing you to develop new
-cubes.
+There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can acces a
+list of availble cubes using ``apt-cache search cubicweb`` or at the
+`CubicWeb.org Forge`_.
 
 .. note::
 
-   `cubicweb-dev` will install basic sqlite support. You can easily setup
-   `cubicweb with other database`_ using the following virtual packages :
-   `cubicweb-postgresql-support` contains necessary dependency for using
-   `cubicweb with postgresql datatabase`_ and `cubicweb-mysql-support` contains
-   necessary dependency for using `cubicweb with mysql database`_ .
-
-There is also a wide variety of :ref:`cubes <AvailableCubes>` listed on the
-`CubicWeb.org Forge`_ available as debian packages and tarball.
+  `cubicweb-dev` will install basic sqlite support. You can easily setup
+  :ref:`cubicweb with other database <DatabaseInstallation>` using the following virtual packages :
 
-The repositories are signed with `Logilab's gnupg key`_. To avoid warning on
-"apt-get update":
+  * `cubicweb-postgresql-support` contains necessary dependency for
+    using :ref:`cubicweb with postgresql datatabase <PostgresqlConfiguration>`
 
-1. become root using sudo
-2. download http://download.logilab.org/logilab-dists-key.asc using e.g. wget
-3. run "apt-key add logilab-dists-key.asc"
-4. re-run apt-get update (manually or through the package manager, whichever you prefer)
+  * `cubicweb-mysql-support` contains necessary dependency for using
+    :ref:`cubicweb with mysql database <MySqlConfiguration>`.
 
+.. _`list of sources`: http://wiki.debian.org/SourcesList
 .. _`Logilab's gnupg key`: http://download.logilab.org/logilab-dists-key.asc
 .. _`CubicWeb.org Forge`: http://www.cubicweb.org/project/
-.. _`cubicweb with other database`: DatabaseInstallation_
-.. _`cubicweb with postgresql datatabase` : PostgresqlConfiguration_
-.. _`cubicweb with mysql database` : MySqlConfiguration_
+
+.. _WindowsInstallation:
+
+Windows Install
+---------------
+
+You need to have `python`_ version >= 2.5 and < 3 installed.
+
+Then your best option is probably the :ref:`EasyInstallInstallation`.
+In fact it is a pure python packages manager which lacks in Windows.
+It helps users to install python packages along with dependencies,
+searching for suitable pre-compiled binaries on the
+`The Python Package Index`_.
 
+Moreover, if you want better control over the process as well as
+a suitable development environment or if you are having problems with
+`easy_install`, move right away to :ref:`SetUpWindowsEnv`.
+
+.. _python:  http://www.python.org/
+.. _`The Python Package Index`: http://pypi.python.org
+
+.. _VirtualenvInstallation:
+
+`Virtualenv` install
+--------------------
+
+Since version 3.9, |cubicweb| can be safely installed, used and contained inside
+a `virtualenv`_. You can use either 
+:ref:`pip <PipInstallation>` or
+:ref:`easy_install <EasyInstallInstallation>` to install |cubicweb| inside an
+activated virtual environment.
 
 .. _PipInstallation:
 
-Installation with pip
-`````````````````````
+`pip` install
+-------------
+
+Using pip_ is the recommended way to install |cubicweb|. pip_ is a
+smart python utility that lets you automatically download, build,
+install, and manage python packages and their dependencies. It is full
+compatible with `virtualenv`_.
 
-pip_ is a smart python utility that lets you automatically download, build,
-install, and manage python packages and their dependencies.
+pip_ install the packages from sources published on the
+*The Python Package Index* (PyPI_).
+You need a compilation environment because some dependencies have C
+extensions. If you definitively wont, installing 
+`Lxml <http://codespeak.net/lxml/>`_,
+`Twisted <http://twistedmatrix.com/trac/>`_ and 
+`libgecode <http://www.gecode.org/>`_ will help.
 
-|cubicweb| and its cubes have been pip_ installable since version 3.9. Search
-for them on pypi_::
+To install |cubicweb| and all dependencies just use the following command
+line::
 
   pip install cubicweb
+
+There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can acces a
+list of availble cubes on
+`PyPI <http://pypi.python.org/pypi?%3Aaction=search&term=cubicweb&submit=search>`_ 
+or at the `CubicWeb.org Forge`_.
+
+For example, installing the *blog cube* is achieved by::
+
   pip install cubicweb-blog
 
-.. note::
-
-    Pip is the recommended way to install |cubicweb| if there is no binary
-    package available on your system or you want to install it inside a
-    `virtualenv`_. However pip doesn't install binary package and may require
-    several compilation steps while installing |cubicweb| dependencies. If you
-    don't have a compilation environment you should use  `easy_install
-    installation`_ to install |cubicweb|.
-
-    Once, |cubicweb| is installed, this limitation doesn't apply when installing
-    cubes.
-
-
-.. _pip: http://pypi.python.org/pypi/pip
-.. _pypi: http://pypi.python.org/pypi?%3Aaction=search&term=cubicweb
-.. _`easy_install installation`: EasyInstallInstallation_
-
-
-.. warning::
-
-  |cubicweb| depends upon the `lxml` python module. This module contains ``C``
-  code that must be compiled.  To successfully install |cubicweb| with pip, you
-  must either have an environment ables to compile Python ``C`` extensions or
-  preinstall lxml from a binary package.
-
-.. note::
-
-  For better performance the setup processor will compile a ``C`` extension for
-  the :ref:`RQL <RQL>` language if you have an environment ables to compile
-  Python ``C`` extensions and the `gecode library`_.  Otherwise, a pure python
-  alternative will be used for degraded performance.
-
 .. _`gecode library`: http://www.gecode.org/
-.. _`easy_install`:   http://packages.python.org/distribute/easy_install.html
 
 
 .. _EasyInstallInstallation:
 
-Installation with EasyInstall
-``````````````````````````````
+`easy_install` install
+----------------------
+
+If you are not a Windows user and you have a compilation environment,
+we recommend you to use the PipInstallation_.
+
+Install |cubicweb| version >= 3.9 with::
+
+  easy_install cubicweb
+
+There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can acces a
+list of availble cubes on `PyPI
+<http://pypi.python.org/pypi?%3Aaction=search&term=cubicweb&submit=search>`_
+or at the `CubicWeb.org Forge`_. 
+
+For example, installing the *blog cube* is achieved by::
+
+  easy_install cubicweb-blog
 
 .. note::
 
-    We don't recommend the use of `easy_install` and setuptools in the generic
-    case. However as easy_install is currently the sole pure python package
-    system that support binary installation. Using `easy_install` is currently
-    the easiest way to install |cubicweb| when you don't have a compilation
-    environment set-up or Debian based distribution.
-
-
-|cubicweb| is easy_install_ installable for version 3.9::
+  If you encounter problem with :ref:`cubes <AvailableCubes>` installation,
+  considere using :ref:`PipInstallation` which is more stable
+  but do not offer binaries installation.
 
-  easy_install cubicweb
-
-.. warning::
-
-    Cubes are **not** is easy_install_ installable. But they are
-    `pip installable`_
-
-
+.. _`easy_install`:   http://packages.python.org/distribute/easy_install.html
 
 
 .. _SourceInstallation:
 
 Install from source
-```````````````````
+-------------------
 
 .. _TarballInstallation:
 
-You can download the archive containing the sources from our `download site`_ at::
-
-  http://download.logilab.org/pub/cubicweb/
-
-.. _`download site`: http://download.logilab.org/pub/cubicweb/
+You can download the archive containing the sources from our download site at
+`http://download.logilab.org/pub/cubicweb/ <http://download.logilab.org/pub/cubicweb/>`_.
 
 Make sure you also have all the :ref:`InstallDependencies`.
 
+Once uncompressed, you can install the framework from inside the uncompressed
+folder with::
+
+  python setup.py install
+
+Or you can run |cubicweb| directly from the source directory by
+setting the :ref:`resource mode <RessourcesConfiguration>` to `user`. This will
+ease the development with the framework.
+
+There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can acces a
+list of availble cubes at the `CubicWeb.org Forge`_.
+
+
 .. _MercurialInstallation:
 
 Install from version control system
-```````````````````````````````````
+-----------------------------------
 
-You can keep up to date with on-going development by using Mercurial::
+To install the lastest stable development version from our Mercurial
+repository, you can use `pip` (you need a compilation devlopment to perform
+such install)::
+
+  pip install -e "hg+http://www.logilab.org/hg/cubicweb/@stable#egg=cubicweb"
 
-  hg clone http://hg.logilab.org/cubicweb
+Or, to develop with the framework you can keep up to date with on-going
+development by cloning our :ref:`Mercurial <MercurialPresentation>`
+repository::
 
-See :ref:`MercurialPresentation` for more details about Mercurial.
+  hg clone -u stable http://hg.logilab.org/cubicweb # stable branch
+  hg clone http://hg.logilab.org/cubicweb # very lastest (development branch)
 
-A practical way to get many of CubicWeb's dependencies and a nice set
+Then a practical way to get many of CubicWeb's dependencies and a nice set
 of base cubes is to run the `clone_deps.py` script located in
 `cubicweb/bin/`::
 
@@ -196,381 +250,20 @@
 
 (Windows users should replace slashes with antislashes).
 
-This script will clone a set of mercurial repositories into in the
-directory containing the CubicWeb repository, and update them to the
+This script will clone a set of mercurial repositories into the
+directory containing the ``cubicweb`` repository, and update them to the
 latest published version tag (if any).
 
-When cloning a repository, you might be set in a development branch
-(the 'default' branch). You should check that the branches of the
-repositories are set to 'stable' (using `hg up stable` for each one)
-if you do not intend to develop the framework itself.
+.. note::
 
-Even better, `hg tags` will display a list of tags in reverse
-chronological order. One reasonnable way to get to a working version
-is to pick the latest published version (as done by the `clone_deps`
-script). These look like `cubicweb-debian-version-3.9.7-1`. Typing::
+  In every cloned repositories, a `hg tags` will display a list of
+  tags in reverse chronological order. One reasonnable option is to go to a
+  taged version: the latest published version or example, as done by
+  the `clone_deps` script)::
 
- hg update cubicweb-debian-version-3.9.7-1
-
-will update the repository files to this version.
+   hg update cubicweb-debian-version-3.10.7-1
 
 Make sure you also have all the :ref:`InstallDependencies`.
 
-
-.. _WindowsInstallation:
-
-Windows installation
-````````````````````
-
-Your best option is probably the :ref:`PipInstallation`. If it does not work or
-if you want more control over the process, continue with the following
-instructions.
-
-Base elements
-~~~~~~~~~~~~~
-
-Setting up a windows development environment is not too complicated but requires
-a series of small steps. What is proposed there is only an example of what can be
-done. We assume everything goes into `C:\\` in this document. Adjusting the
-installation drive should be straightforward.
-
-You should start by downloading and installing Python version >= 2.5 and < 3.
-
-An alternative option would be installing the Python(x,y)
-distribution. Python(x,y) is not a requirement, but 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). Download it from this page::
-
-  http://code.google.com/p/pythonxy/wiki/Downloads
-
-Then you must grab Twisted. There is a windows installer directly available from
-this page::
-
-  http://twistedmatrix.com/trac/
-
-A windows installer for lxml will be found there::
-
-  http://pypi.python.org/pypi/lxml/2.2.1
-
-Check out the lxml-2.2.1-win32-py2.5.exe file. More recent bugfix
-releases should probably work, too.
-
-You should find postgresql 8.4 there::
-
-  http://www.enterprisedb.com/products/pgdownload.do#windows
-
-The python drivers for posgtresql are to be found there::
-
-  http://www.stickpeople.com/projects/python/win-psycopg/#Version2
-
-Please be careful to select the right python (2.5) and postgres (8.4) versions.
-
-A windows compiled recent version of gettext::
-
-  http://download.logilab.org/pub/gettext/gettext-0.17-win32-setup.exe
-
-A pre-compiled version of rql for windows (take care of retrieving the
-most recent version available there)::
-
-  http://download.logilab.org/pub/rql/rql-0.23.0.win32-py2.5.exe
-
-Pyro enables remote access to cubicweb repository instances. Get it there::
-
-  http://sourceforge.net/projects/pyro/files/
-
-To access LDAP/Active directory directories, we need the python-ldap
-package. Windows binaries are available from::
-
-  http://www.osuch.org/python-ldap
-
-Check out the latest release.
-
-Having graphviz will allow schema drawings, which is quite recommended (albeit
-not mandatory). You should get an msi installer there::
-
-  http://www.graphviz.org/Download_windows.php
-
-Simplejson is needed when installing with Python 2.5, but included in the
-standard library for Python >= 2.6. Get it from there::
-
-  http://www.osuch.org/python-simplejson%3Awin32
-
-Make sure you also have all the :ref:`InstallDependencies` that are not specific
-to Windows.
-
-Tools
-~~~~~
-
-Get mercurial + its standard windows GUI (TortoiseHG) there (the latest is the
-greatest)::
-
-  http://bitbucket.org/tortoisehg/stable/wiki/download
-
-If you need to peruse mercurial over ssh, it can be helpful to get an ssh client
-like Putty::
-
-  http://www.putty.org/
-
-Integration of mercurial and Eclipse is convenient enough that we want
-it. Instructions are set there, in the `Download & Install` section::
-
-  http://www.vectrace.com/mercurialeclipse/
-
-Getting the sources
-~~~~~~~~~~~~~~~~~~~
-
-You can either download the latest release (see
-:ref:`SourceInstallation`) or get the development version using
-Mercurial (see :ref:`MercurialInstallation` and below), which is more
-convenient.
-
-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
-variables.
-
-We will consider only user variables. First, the PATH variable. You should ensure
-it contains, separated by semi-colons, and assuming you are logged in as user
-Jane::
-
-  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 then find
-C:\\etc\\cubicweb.d\\my_instance\\win32svc.py that has to be used as follows::
-
-  win32svc install
-
-This should just register your instance as a windows service. A simple::
-
-  net start cubicweb-my_instance
-
-should start the service.
-
-
-Other dependencies
-``````````````````
-
-You can also install:
-
-* `pyro` if you wish the repository to be accessible through Pyro
-  or if the client and the server are not running on the same machine
-  (in which case the packages will have to be installed on both
-  machines)
-
-* `python-ldap` if you plan to use a LDAP source on the server
-
-
-.. _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:
-
-PostgreSQL configuration
-````````````````````````
-
-For installation, please refer to the `PostgreSQL project online documentation`_.
-
-.. _`PostgreSQL project online documentation`: http://www.postgresql.org/
-
-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
-  with::
-
-    $ 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:
-
-MySql configuration
-```````````````````
-You must add the following lines in ``/etc/mysql/my.cnf`` file::
-
-    transaction-isolation=READ-COMMITTED
-    default-storage-engine=INNODB
-    default-character-set=utf8
-    max_allowed_packet = 128M
-
-.. Note::
-    It is unclear whether mysql supports indexed string of arbitrary length or
-    not.
-
-
-.. _SQLServerConfiguration:
-
-SQLServer configuration
-```````````````````````
-
-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
-shown)::
-
-  [system]
-  db-driver=sqlserver2005
-  db-user=someuser
-  # database password not needed
-  #db-password=toto123
-  #db-create/init may ask for a pwd: just say anything
-  db-extra-arguments=Trusted_Connection
-  db-encoding=utf8
-
-
-
-.. _SQLiteConfiguration:
-
-SQLite configuration
-````````````````````
-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
-
-
-Cubicweb resources configuration
---------------------------------
-
-.. autodocstring:: cubicweb.cwconfig
+.. _`pip`: http://pip.openplans.org/
+.. _`virtualenv`: http://virtualenv.openplans.org/
--- a/doc/book/en/index.rst	Thu Apr 14 11:36:47 2011 +0200
+++ b/doc/book/en/index.rst	Wed Apr 06 12:33:39 2011 +0200
@@ -38,7 +38,7 @@
 
 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_.