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.
Also, since version 3.9, can be safely installed, used and contained inside a virtualenv.
Depending on the distribution you are using, add the appropriate line to your list of sources (for example by editing /etc/apt/sources.list).
For Debian Lenny:
deb http://ftp.logilab.org/dists/ lenny/
For Debian Sid:
deb http://ftp.logilab.org/dists/ sid/
For Ubuntu Hardy:
deb http://ftp.logilab.org/dists/ hardy/
You can now install the required packages with the following command:
apt-get update
apt-get install cubicweb cubicweb-dev
cubicweb installs the framework itself, allowing you to create new instances.
cubicweb-dev installs the development environment allowing you to develop new cubes.
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 cubes listed on the CubicWeb.org Forge available as debian packages and tarball.
The repositories are signed with Logilab’s gnupg key. To avoid warning on “apt-get update”:
pip is a smart python utility that lets you automatically download, build, install, and manage python packages and their dependencies.
CubicWeb and its cubes have been pip installable since version 3.9. Search for them on pypi:
pip install cubicweb
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.
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 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.
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:
easy_install cubicweb
Warning
Cubes are not is easy_install installable. But they are pip installable
You can download the archive containing the sources from our ftp site at:
http://ftp.logilab.org/pub/cubicweb/
Make sure you also have all the Installation dependencies.
You can keep up to date with on-going development by using Mercurial:
hg clone http://hg.logilab.org/cubicweb
See Introducing Mercurial for more details about Mercurial.
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/:
python cubicweb/bin/clone_deps.py
(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 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.
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:
hg update cubicweb-debian-version-3.9.7-1
will update the repository files to this version.
Make sure you also have all the Installation dependencies.
Your best option is probably the Installation with pip. If it does not work or if you want more control over the process, continue with the following instructions.
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://ftp.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://ftp.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 Installation dependencies that are not specific to Windows.
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/
You can either download the latest release (see Install from source) or get the development version using Mercurial (see Install from version control system and below), which is more convenient.
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.
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.
You can also install:
Each instance can be configured with its own database connection information, that will be stored in the instance’s 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.
For installation, please refer to the PostgreSQL project online documentation.
You need to install the three following packages: postgresql-8.X, postgresql-client-8.X, and postgresql-plpython-8.X. If you run postgres version prior to 8.3, you’ll also need the postgresql-contrib-8.X package for full-text search extension.
If you run postgres on another host than the CubicWeb repository, you should install the postgresql-client package on the CubicWeb host, and others on the database host.
Note
If you already have an existing cluster and PostgreSQL server running, you do not need to execute the initilization step of your PostgreSQL database unless you want a specific cluster for CubicWeb databases or if your existing cluster doesn’t use the UTF8 encoding (see note below).
First, initialize a PostgreSQL cluster with the command initdb.
$ initdb -E UTF8 -D /path/to/pgsql
Notice the encoding specification. This is necessary since CubicWeb usually want UTF8 encoded database. If you use a cluster with the wrong encoding, you’ll get error like:
new encoding (UTF8) is incompatible with the encoding of the template database (SQL_ASCII)
HINT: Use the same encoding as in the template database, or use template0 as template.
Once initialized, start the database server PostgreSQL with the command:
$ postgres -D /path/to/psql
If you cannot execute this command due to permission issues, please make sure that your username has write access on the database.
$ chown username /path/to/pgsql
The database authentication can be either set to ident sameuser or md5. If set to md5, make sure to use an existing user of your database. If set to ident sameuser, make sure that your client’s operating system user name has a matching user in the database. If not, please do as follow to create a user:
$ su
$ su - postgres
$ createuser -s -P username
The option -P (for password prompt), will encrypt the password with the method set in the configuration file 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:
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
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.
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
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.
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 :
A resource mode is a predefined set of settings for various resources directories, such as cubes, instances, etc. to ease development with the framework. There are two running modes with CubicWeb:
system: resources are searched / created in the system directories (eg usually requiring root access):
where <INSTALL_PREFIX> is the detected installation prefix (‘/usr/local’ for instance).
user: resources are searched / created in the user home directory:
Notice that each resource path may be explicitly set using an environment variable if the default doesn’t suit your needs. Here are the default resource directories that are affected according to mode:
system:
CW_INSTANCES_DIR = <INSTALL_PREFIX>/etc/cubicweb.d/
CW_INSTANCES_DATA_DIR = /var/lib/cubicweb/instances/
CW_RUNTIME_DIR = /var/run/cubicweb/
user:
CW_INSTANCES_DIR = ~/etc/cubicweb.d/
CW_INSTANCES_DATA_DIR = ~/etc/cubicweb.d/
CW_RUNTIME_DIR = /tmp
Cubes search path is also affected, see the Cubes section.
By default, the mode automatically set to user if a .hg directory is found in the cubicweb package, else it’s set to system. You can force this by setting the CW_MODE environment variable to either user or system so you can easily:
If you’ve a doubt about the mode you’re currently running, check the first line outputed by the cubicweb-ctl list command.
Also, if cubicweb is a mercurial checkout located in <CW_SOFTWARE_ROOT>:
If you installed CubicWeb by cloning the Mercurial forest or from source distribution, then you will need to update the environment variable PYTHONPATH by adding the path to the forest cubicweb:
Add the following lines to either .bashrc or .bash_profile to configure your development environment
export PYTHONPATH=/full/path/to/cubicweb-forest
If you installed CubicWeb with packages, no configuration is required and your new cubes will be placed in /usr/share/cubicweb/cubes and your instances will be placed in /etc/cubicweb.d.
Here are all environment variables that may be used to configure CubicWeb: