# HG changeset patch # User Alain Leufroy # Date 1302086019 -7200 # Node ID e88c57c10b34bf48207a7a0aa9f81a26ad27bf0f # Parent a4a115aab0868b8b66986ea6db4c1cd79c8454af [doc] major update of the install documentation diff -r a4a115aab086 -r e88c57c10b34 doc/book/en/admin/config.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 + + diff -r a4a115aab086 -r e88c57c10b34 doc/book/en/admin/instance-config.rst --- 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) / / .conf diff -r a4a115aab086 -r e88c57c10b34 doc/book/en/admin/setup-windows.rst --- /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 `_). + 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 ` +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 `: + +* 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 diff -r a4a115aab086 -r e88c57c10b34 doc/book/en/admin/setup.rst --- 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 `_). + + - `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 `_. -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 `. 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 ` 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 ` 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 ` -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 `. +.. _`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 ` or +:ref:`easy_install ` 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 `_, +`Twisted `_ and +`libgecode `_ 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 `. You can acces a +list of availble cubes on +`PyPI `_ +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 ` 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 `. You can acces a +list of availble cubes on `PyPI +`_ +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 ` 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/ `_. 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 ` to `user`. This will +ease the development with the framework. + +There is also a wide variety of :ref:`cubes `. 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 ` +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/ diff -r a4a115aab086 -r e88c57c10b34 doc/book/en/index.rst --- 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_.