setup.rst 8.81 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

8
9
There are different simple ways to install |cubicweb| and its
dependencies depending on your requirements:
10

11
12
* `Distribution-specific installation`. This option shows you how to
  easily install |cubicweb| and its requirements on your system:
13

14
15
16
  - `Installation on Debian/Ubuntu`_ 
  - `Installation on Windows`_
  - `Install in a virtualenv`_
17

18
19
20
* `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`_:
21

22
23
  - `Installation with pip`_
  - `Installation with easy_install`_
24

25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
* `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`_

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_
42

43

44
45
.. _DebianInstallation:

46
47
48
49
50
51
52
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.
53

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

57
For Debian Squeeze (stable)::
58

59
  deb http://download.logilab.org/production/ squeeze/
60

61
For Debian Sid (unstable)::
62

63
  deb http://download.logilab.org/production/ sid/
64

65
For Ubuntu Lucid (Long Term Support) and newer::
66

67
  deb http://download.logilab.org/production/ lucid/
68

69
70
71
72
73
74
  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::
75

76
77
78
  wget -q http://download.logilab.org/logilab-dists-key.asc -O- | sudo apt-key add -

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
80
  apt-get update
Sylvain Thénault's avatar
Sylvain Thénault committed
81
  apt-get install cubicweb cubicweb-dev
82

83
84
85
``cubicweb`` installs the framework itself, allowing you to create new
instances. ``cubicweb-dev`` installs the development environment
allowing you to develop new cubes.
86

87
88
89
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`_.
90

91
92
.. note::

93
94
  `cubicweb-dev` will install basic sqlite support. You can easily setup
  :ref:`cubicweb with other database <DatabaseInstallation>` using the following virtual packages :
95

96
97
  * `cubicweb-postgresql-support` contains necessary dependency for
    using :ref:`cubicweb with postgresql datatabase <PostgresqlConfiguration>`
98

99
100
  * `cubicweb-mysql-support` contains necessary dependency for using
    :ref:`cubicweb with mysql database <MySqlConfiguration>`.
101

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

106
.. _WindowsInstallation:
107

108
109
Windows Install
---------------
110

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

113
114
115
116
117
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`_.
118

119
120
121
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`.
122

123
124
.. _python:  http://www.python.org/
.. _`The Python Package Index`: http://pypi.python.org
125

126
.. _VirtualenvInstallation:
127

128
129
`Virtualenv` install
--------------------
130

131
132
133
134
135
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.
136

137
.. _PipInstallation:
138

139
140
`pip` install
-------------
141

142
143
144
145
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`_.
Adrien Chauve's avatar
Adrien Chauve committed
146

147
148
149
150
151
152
153
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.
154

155
156
To install |cubicweb| and all dependencies just use the following command
line::
157

158
159
160
161
162
163
  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`_.
164

165
166
167
For example, installing the *blog cube* is achieved by::

  pip install cubicweb-blog
168
169
170
171
172
173

.. _`gecode library`: http://www.gecode.org/


.. _EasyInstallInstallation:

174
175
`easy_install` install
----------------------
176

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

180
Install |cubicweb| version >= 3.9 with::
181

182
  easy_install cubicweb
183

184
185
186
187
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`_. 
188

189
For example, installing the *blog cube* is achieved by::
190

191
  easy_install cubicweb-blog
192

193
.. note::
194

195
196
197
  If you encounter problem with :ref:`cubes <AvailableCubes>` installation,
  considere using :ref:`PipInstallation` which is more stable
  but do not offer binaries installation.
198

199
.. _`easy_install`:   http://packages.python.org/distribute/easy_install.html
200
201
202


.. _SourceInstallation:
203

204
Install from source
205
-------------------
206

207
208
.. _TarballInstallation:

209
210
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/>`_.
211

212
Make sure you also have all the :ref:`InstallDependencies`.
213

214
215
216
217
218
219
220
221
222
223
224
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`_.
225

226

227
.. _MercurialInstallation:
228

229
Install from version control system
230
-----------------------------------
231

232
233
234
To install the lastest stable development version from our Mercurial
repository, you can use `pip` (you need a compilation devlopment to perform
such install)::
235

236
  pip install -e "hg+http://www.logilab.org/hg/cubicweb/@stable#egg=cubicweb"
237

238
239
240
Or, to develop with the framework you can keep up to date with on-going
development by cloning our :ref:`Mercurial <MercurialPresentation>`
repository::
241

242
243
244
245
  hg clone -u stable http://hg.logilab.org/cubicweb # stable branch
  hg clone http://hg.logilab.org/cubicweb # very lastest (development branch)

Then a practical way to get many of CubicWeb's dependencies and a nice set
246
247
248
249
250
251
252
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).

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

257
.. note::
258

259
260
261
262
  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)::
263

264
   hg update cubicweb-debian-version-3.10.7-1
265

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

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