setup.rst 8.45 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
53
`list of sources` (for example by editing ``/etc/apt/sources.list``), replacing
``<release>`` with e.g. ``wheezy`` or ``trusty``::
54

55
  deb http://download.logilab.org/production/ <release>/
56

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

60
  wget -O/etc/apt/trusted.gpg.d/logilab.gpg https://www.logilab.fr/logilab-debian-keyring.gpg
61
62

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
64
  apt-get update
Sylvain Thénault's avatar
Sylvain Thénault committed
65
  apt-get install cubicweb cubicweb-dev
66

67
68
69
70
71
72
  # if you want pyramid, the recommended application server
  apt-get install pyramid-cubicweb

  # or if you want twisted (considered deprecated)
  apt-get install cubicweb-twisted

73
74
75
``cubicweb`` installs the framework itself, allowing you to create new
instances. ``cubicweb-dev`` installs the development environment
allowing you to develop new cubes.
76

Nicolas Chauvat's avatar
Nicolas Chauvat committed
77
78
79
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`_.
80

81
82
.. note::

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

87
  * `cubicweb-postgresql-support` contains the necessary dependencies for
88
    using :ref:`cubicweb with postgresql datatabase <PostgresqlConfiguration>`
89

90
  * `cubicweb-mysql-support` contains the necessary dependencies for using
91
    :ref:`cubicweb with mysql database <MySqlConfiguration>`.
92

93
.. _`list of sources`: http://wiki.debian.org/SourcesList
94
.. _`Logilab's gnupg key`: https://www.logilab.fr/logilab-debian-keyring.gpg
95
96
.. _`CubicWeb.org Forge`: http://www.cubicweb.org/project/

97
.. _WindowsInstallation:
98

99
100
Windows Install
---------------
101

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
104
105
106
107
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`_.
108

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

113
114
.. _python:  http://www.python.org/
.. _`The Python Package Index`: http://pypi.python.org
115

116
.. _VirtualenvInstallation:
117

118
119
`Virtualenv` install
--------------------
120

121
122
123
124
|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.
125

126
.. _PipInstallation:
127

128
129
`pip` install
-------------
130

131
132
133
134
`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
135
136
137
138

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

A working compilation chain is needed to build the modules that include C
139
extensions. If you really do not want to compile anything, installing `lxml <http://lxml.de/>`_,
Sylvain Thénault's avatar
Sylvain Thénault committed
140
141
`Twisted Web <http://twistedmatrix.com/trac/wiki/Downloads/>`_ and `libgecode
<http://www.gecode.org/>`_ will help.
142

143
144
145
146
147
148
149
150
151
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
152
153
154
155
156
157
158
159
160
<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

Make sure to choose the correct architecture and version of Python.
161
162

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

164
165
166
167
168
  # for pyramid, the recommended application server
  pip install cubicweb[pyramid]

  # or for twisted, considered deprecated (used by "cubicweb-ctl")
  pip install cubicweb[etwist]
169

Paul Tonelli's avatar
Paul Tonelli committed
170
Many other :ref:`cubes <AvailableCubes>` are available. A list is available at
Nicolas Chauvat's avatar
Nicolas Chauvat committed
171
172
`PyPI <http://pypi.python.org/pypi?%3Aaction=search&term=cubicweb&submit=search>`_
or at the `CubicWeb.org forge`_.
173

174
175
176
For example, installing the *blog cube* is achieved by::

  pip install cubicweb-blog
177
178
179

.. _EasyInstallInstallation:

180
181
`easy_install` install
----------------------
182

Nicolas Chauvat's avatar
Nicolas Chauvat committed
183
184
185
186
.. note::

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

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

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

193
  easy_install cubicweb
194

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

200
For example, installing the *blog cube* is achieved by::
201

202
  easy_install cubicweb-blog
203

204
.. note::
205

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

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


.. _SourceInstallation:
214

215
Install from source
216
-------------------
217

218
219
.. _TarballInstallation:

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

223
Make sure you also have all the :ref:`InstallDependencies`.
224

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

237

238
.. _MercurialInstallation:
239

240
Install from version control system
241
-----------------------------------
242

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

246
  hg clone -u 'last(tag())' http://hg.logilab.org/cubicweb # stable version
Nicolas Chauvat's avatar
Nicolas Chauvat committed
247
  hg clone http://hg.logilab.org/cubicweb # development branch
248

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