--- /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_.