setup.rst 9.01 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 6.0 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 12.04 Precise Pangolin (Long Term Support) and newer::
63

64
  deb http://download.logilab.org/production/ precise/
65
66
67

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

69
70
71
  wget -q http://download.logilab.org/logilab-dists-key.asc -O- | sudo apt-key add -

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
73
  apt-get update
Sylvain Thénault's avatar
Sylvain Thénault committed
74
  apt-get install cubicweb cubicweb-dev
75

76
77
78
``cubicweb`` installs the framework itself, allowing you to create new
instances. ``cubicweb-dev`` installs the development environment
allowing you to develop new cubes.
79

Nicolas Chauvat's avatar
Nicolas Chauvat committed
80
81
82
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`_.
83

84
85
.. note::

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

90
  * `cubicweb-postgresql-support` contains the necessary dependencies for
91
    using :ref:`cubicweb with postgresql datatabase <PostgresqlConfiguration>`
92

93
  * `cubicweb-mysql-support` contains the necessary dependencies for using
94
    :ref:`cubicweb with mysql database <MySqlConfiguration>`.
95

96
.. _`list of sources`: http://wiki.debian.org/SourcesList
97
.. _`Logilab's gnupg key`: http://download.logilab.org/logilab-dists-key.asc
98
99
.. _`CubicWeb.org Forge`: http://www.cubicweb.org/project/

100
.. _WindowsInstallation:
101

102
103
Windows Install
---------------
104

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
107
108
109
110
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`_.
111

Nicolas Chauvat's avatar
Nicolas Chauvat committed
112
113
114
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`.
115

116
117
.. _python:  http://www.python.org/
.. _`The Python Package Index`: http://pypi.python.org
118

119
.. _VirtualenvInstallation:
120

121
122
`Virtualenv` install
--------------------
123

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

129
.. _PipInstallation:
130

131
132
`pip` install
-------------
133

134
135
136
137
`pip <http://pip.openplans.org/>`_ is a python tool 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`_.
Nicolas Chauvat's avatar
Nicolas Chauvat committed
138
139
140
141

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

A working compilation chain is needed to build the modules that include C
Sylvain Thénault's avatar
Sylvain Thénault committed
142
143
144
extensions. If you definitively wont, installing `Lxml <http://lxml.de/>`_,
`Twisted Web <http://twistedmatrix.com/trac/wiki/Downloads/>`_ and `libgecode
<http://www.gecode.org/>`_ will help.
145

146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
For Debian, these minimal dependencies can be obtained by doing::

  apt-get install gcc python-pip python-dev python-lxml

or, if you prefer to get as much as possible from pip::

  apt-get install gcc python-pip python-dev libxslt1-dev libxml2-dev

For Windows, you can install pre-built packages (possible `source
<http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_). For a minimal setup, install
`pip <http://www.lfd.uci.edu/~gohlke/pythonlibs/#pip>`_, `setuptools
<http://www.lfd.uci.edu/~gohlke/pythonlibs/#setuptools>`_, `libxml-python
<http://www.lfd.uci.edu/~gohlke/pythonlibs/#libxml-python>`_, `lxml
<http://www.lfd.uci.edu/~gohlke/pythonlibs/#lxml>`_ and `twisted
<http://www.lfd.uci.edu/~gohlke/pythonlibs/#twisted>`_ from this source making
sure to choose the correct architecture and version of Python.

Finally, install |cubicweb| and its dependencies, by running::
164

165
166
  pip install cubicweb

Nicolas Chauvat's avatar
Nicolas Chauvat committed
167
168
169
170
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`_.
171

172
173
174
For example, installing the *blog cube* is achieved by::

  pip install cubicweb-blog
175
176
177

.. _EasyInstallInstallation:

178
179
`easy_install` install
----------------------
180

Nicolas Chauvat's avatar
Nicolas Chauvat committed
181
182
183
184
.. note::

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
186
187
188
189
`easy_install`_ is a python utility that helps downloading, installing, and
managing python packages and their dependencies.

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

191
  easy_install cubicweb
192

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

198
For example, installing the *blog cube* is achieved by::
199

200
  easy_install cubicweb-blog
201

202
.. note::
203

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
208
.. _`easy_install`: http://packages.python.org/distribute/easy_install.html
209
210
211


.. _SourceInstallation:
212

213
Install from source
214
-------------------
215

216
217
.. _TarballInstallation:

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

221
Make sure you also have all the :ref:`InstallDependencies`.
222

223
224
225
226
227
228
229
230
231
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
232
There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can access a
233
list of availble cubes at the `CubicWeb.org Forge`_.
234

235

236
.. _MercurialInstallation:
237

238
Install from version control system
239
-----------------------------------
240

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

244
  hg clone -u stable http://hg.logilab.org/cubicweb # stable branch
Nicolas Chauvat's avatar
Nicolas Chauvat committed
245
  hg clone http://hg.logilab.org/cubicweb # development branch
246

Nicolas Chauvat's avatar
Nicolas Chauvat committed
247
248
To get many of CubicWeb's dependencies and a nice set of base cubes, run the
`clone_deps.py` script located in `cubicweb/bin/`::
249
250
251
252
253

  python cubicweb/bin/clone_deps.py

(Windows users should replace slashes with antislashes).

254
255
This script will clone a set of mercurial repositories into the
directory containing the ``cubicweb`` repository, and update them to the
256
257
latest published version tag (if any).

258
.. note::
259

260
261
  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
262
  tagged version: the latest published version or example, as done by
263
  the `clone_deps` script)::
264

Nicolas Chauvat's avatar
Nicolas Chauvat committed
265
   hg update cubicweb-version-3.12.2
266

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