setup.rst 8.38 KB
Newer Older
1
.. -*- coding: utf-8 -*-
Adrien Di Mascio's avatar
Adrien Di Mascio committed
2

Sandrine Ribeau's avatar
Sandrine Ribeau committed
3
.. _SetUpEnv:
Adrien Di Mascio's avatar
Adrien Di Mascio committed
4

5
6
Installation of a *CubicWeb* environment
========================================
Adrien Di Mascio's avatar
Adrien Di Mascio committed
7

Nicolas Chauvat's avatar
Nicolas Chauvat committed
8
9
10
11
12
13
Official releases are available from the `CubicWeb.org forge`_ and from
`PyPI`_. Since CubicWeb is developed using `Agile software development
<http://en.wikipedia.org/wiki/Agile_software_development>`_ techniques, releases
happen frequently. In a version numbered X.Y.Z, X changes after a few years when
the API breaks, Y changes after a few weeks when features are added and Z
changes after a few days when bugs are fixed.
14

Nicolas Chauvat's avatar
Nicolas Chauvat committed
15
16
Depending on your needs, you will chose a different way to install CubicWeb on
your system:
17

Nicolas Chauvat's avatar
Nicolas Chauvat committed
18
19
20
21
22
23
- `Installation on Debian/Ubuntu`_
- `Installation on Windows`_
- `Installation in a virtualenv`_
- `Installation with pip`_
- `Installation with easy_install`_
- `Installation from tarball`_
24

Nicolas Chauvat's avatar
Nicolas Chauvat committed
25
If you are a power-user and need the very latest features, you will
26

Nicolas Chauvat's avatar
Nicolas Chauvat committed
27
- `Install from version control`_
28

Nicolas Chauvat's avatar
Nicolas Chauvat committed
29
Once the software is installed, move on to :ref:`ConfigEnv` for better control
30
31
32
33
and advanced features of |cubicweb|.

.. _`Installation on Debian/Ubuntu`: DebianInstallation_
.. _`Installation on Windows`: WindowsInstallation_
Nicolas Chauvat's avatar
Nicolas Chauvat committed
34
.. _`Installation in a virtualenv`: VirtualenvInstallation_
35
36
37
.. _`Installation with pip`: PipInstallation_
.. _`Installation with easy_install`: EasyInstallInstallation_
.. _`Installation from tarball`: TarballInstallation_
Nicolas Chauvat's avatar
Nicolas Chauvat committed
38
.. _`Install from version control`: MercurialInstallation_
39

40

41
42
.. _DebianInstallation:

43
44
45
46
Debian/Ubuntu install
---------------------

|cubicweb| is packaged for Debian/Ubuntu (and derived
Nicolas Chauvat's avatar
Nicolas Chauvat committed
47
48
49
distributions). Their integrated package-management system make
installation and upgrade much easier for users since
dependencies (like databases) are automatically installed.
50

51
Depending on the distribution you are using, add the appropriate line to your
52
`list of sources` (for example by editing ``/etc/apt/sources.list``).
53

54
For Debian Squeeze (stable)::
55

56
  deb http://download.logilab.org/production/ squeeze/
57

58
For Debian Sid (unstable)::
59

60
  deb http://download.logilab.org/production/ sid/
61

62
For Ubuntu Lucid (Long Term Support) and newer::
63

64
  deb http://download.logilab.org/production/ lucid/
65

66
67
68
69
70
71
  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>`_.

The repositories are signed with the `Logilab's gnupg key`_. You can download
and register the key to avoid warnings::
72

73
74
75
  wget -q http://download.logilab.org/logilab-dists-key.asc -O- | sudo apt-key add -

Update your list of packages and perform the installation::
76

Nicolas Chauvat's avatar
Nicolas Chauvat committed
77
  apt-get update
Sylvain Thénault's avatar
Sylvain Thénault committed
78
  apt-get install cubicweb cubicweb-dev
79

80
81
82
``cubicweb`` installs the framework itself, allowing you to create new
instances. ``cubicweb-dev`` installs the development environment
allowing you to develop new cubes.
83

Nicolas Chauvat's avatar
Nicolas Chauvat committed
84
85
86
There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can access a
list of available cubes using ``apt-cache search cubicweb`` or at the
`CubicWeb.org forge`_.
87

88
89
.. note::

90
  `cubicweb-dev` will install basic sqlite support. You can easily setup
Nicolas Chauvat's avatar
Nicolas Chauvat committed
91
92
  :ref:`cubicweb with other database <DatabaseInstallation>` using the following
  virtual packages :
93

Nicolas Chauvat's avatar
Nicolas Chauvat committed
94
  * `cubicweb-postgresql-support` contains the necessary dependency for
95
    using :ref:`cubicweb with postgresql datatabase <PostgresqlConfiguration>`
96

Nicolas Chauvat's avatar
Nicolas Chauvat committed
97
  * `cubicweb-mysql-support` contains the necessary dependency for using
98
    :ref:`cubicweb with mysql database <MySqlConfiguration>`.
99

100
.. _`list of sources`: http://wiki.debian.org/SourcesList
101
.. _`Logilab's gnupg key`: http://download.logilab.org/logilab-dists-key.asc
102
103
.. _`CubicWeb.org Forge`: http://www.cubicweb.org/project/

104
.. _WindowsInstallation:
105

106
107
Windows Install
---------------
108

109
You need to have `python`_ version >= 2.5 and < 3 installed.
110

Nicolas Chauvat's avatar
Nicolas Chauvat committed
111
112
113
114
If you want an automated install, your best option is probably the
:ref:`EasyInstallInstallation`. EasyInstall is a tool that helps users to
install python packages along with their dependencies, searching for suitable
pre-compiled binaries on the `The Python Package Index`_.
115

Nicolas Chauvat's avatar
Nicolas Chauvat committed
116
117
118
If you want better control over the process as well as a suitable development
environment or if you are having problems with `easy_install`, read on to
:ref:`SetUpWindowsEnv`.
119

120
121
.. _python:  http://www.python.org/
.. _`The Python Package Index`: http://pypi.python.org
122

123
.. _VirtualenvInstallation:
124

125
126
`Virtualenv` install
--------------------
127

128
Since version 3.9, |cubicweb| can be safely installed, used and contained inside
Nicolas Chauvat's avatar
Nicolas Chauvat committed
129
a `virtualenv`_. You can use either :ref:`pip <PipInstallation>` or
130
131
:ref:`easy_install <EasyInstallInstallation>` to install |cubicweb| inside an
activated virtual environment.
132

133
.. _PipInstallation:
134

135
136
`pip` install
-------------
137

Nicolas Chauvat's avatar
Nicolas Chauvat committed
138
139
140
141
142
143
144
145
146
147
148
pip_ is a python utility that helps downloading, building, installing, and
managing python packages and their dependencies. It is fully compatible with
`virtualenv`_ and installs the packages from sources published on the
`The Python Package Index`_.

.. _`pip`: http://pip.openplans.org/
.. _`virtualenv`: http://virtualenv.openplans.org/

A working compilation chain is needed to build the modules that include C
extensions. If you definitively wont, installing `Lxml
<http://codespeak.net/lxml/>`_, `Twisted <http://twistedmatrix.com/trac/>`_ and
149
`libgecode <http://www.gecode.org/>`_ will help.
150

Nicolas Chauvat's avatar
Nicolas Chauvat committed
151
To install |cubicweb| and its dependencies, just run::
152

153
154
  pip install cubicweb

Nicolas Chauvat's avatar
Nicolas Chauvat committed
155
156
157
158
There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can access a
list of available cubes on
`PyPI <http://pypi.python.org/pypi?%3Aaction=search&term=cubicweb&submit=search>`_
or at the `CubicWeb.org forge`_.
159

160
161
162
For example, installing the *blog cube* is achieved by::

  pip install cubicweb-blog
163
164
165

.. _EasyInstallInstallation:

166
167
`easy_install` install
----------------------
168

Nicolas Chauvat's avatar
Nicolas Chauvat committed
169
170
171
172
.. note::

   If you are not a Windows user and you have a compilation environment, we
   recommend you to use the PipInstallation_.
173

Nicolas Chauvat's avatar
Nicolas Chauvat committed
174
175
176
177
`easy_install`_ is a python utility that helps downloading, installing, and
managing python packages and their dependencies.

Install |cubicweb| and its dependencies, run::
178

179
  easy_install cubicweb
180

Nicolas Chauvat's avatar
Nicolas Chauvat committed
181
182
There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can access a
list of available cubes on `PyPI
183
<http://pypi.python.org/pypi?%3Aaction=search&term=cubicweb&submit=search>`_
Nicolas Chauvat's avatar
Nicolas Chauvat committed
184
or at the `CubicWeb.org Forge`_.
185

186
For example, installing the *blog cube* is achieved by::
187

188
  easy_install cubicweb-blog
189

190
.. note::
191

192
  If you encounter problem with :ref:`cubes <AvailableCubes>` installation,
Nicolas Chauvat's avatar
Nicolas Chauvat committed
193
194
  consider using :ref:`PipInstallation` which is more stable
  but can not installed pre-compiled binaries.
195

Nicolas Chauvat's avatar
Nicolas Chauvat committed
196
.. _`easy_install`: http://packages.python.org/distribute/easy_install.html
197
198
199


.. _SourceInstallation:
200

201
Install from source
202
-------------------
203

204
205
.. _TarballInstallation:

Nicolas Chauvat's avatar
Nicolas Chauvat committed
206
You can download the archive containing the sources from
207
`http://download.logilab.org/pub/cubicweb/ <http://download.logilab.org/pub/cubicweb/>`_.
208

209
Make sure you also have all the :ref:`InstallDependencies`.
210

211
212
213
214
215
216
217
218
219
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.

Nicolas Chauvat's avatar
Nicolas Chauvat committed
220
There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can access a
221
list of availble cubes at the `CubicWeb.org Forge`_.
222

223

224
.. _MercurialInstallation:
225

226
Install from version control system
227
-----------------------------------
228

Nicolas Chauvat's avatar
Nicolas Chauvat committed
229
230
To keep-up with on-going development, clone the :ref:`Mercurial
<MercurialPresentation>` repository::
231

232
  hg clone -u stable http://hg.logilab.org/cubicweb # stable branch
Nicolas Chauvat's avatar
Nicolas Chauvat committed
233
  hg clone http://hg.logilab.org/cubicweb # development branch
234

Nicolas Chauvat's avatar
Nicolas Chauvat committed
235
236
To get many of CubicWeb's dependencies and a nice set of base cubes, run the
`clone_deps.py` script located in `cubicweb/bin/`::
237
238
239
240
241

  python cubicweb/bin/clone_deps.py

(Windows users should replace slashes with antislashes).

242
243
This script will clone a set of mercurial repositories into the
directory containing the ``cubicweb`` repository, and update them to the
244
245
latest published version tag (if any).

246
.. note::
247

248
249
  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
Nicolas Chauvat's avatar
Nicolas Chauvat committed
250
  tagged version: the latest published version or example, as done by
251
  the `clone_deps` script)::
252

Nicolas Chauvat's avatar
Nicolas Chauvat committed
253
   hg update cubicweb-version-3.12.2
254

Nicolas Chauvat's avatar
Nicolas Chauvat committed
255
Make sure you also have all the :ref:`InstallDependencies`.
256