setup.rst 8.1 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
  # if you want pyramid, the recommended application server
  apt-get install pyramid-cubicweb

70
71
72
``cubicweb`` installs the framework itself, allowing you to create new
instances. ``cubicweb-dev`` installs the development environment
allowing you to develop new cubes.
73

Nicolas Chauvat's avatar
Nicolas Chauvat committed
74
75
76
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`_.
77

78
79
.. note::

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

84
  * `cubicweb-postgresql-support` contains the necessary dependencies for
85
    using :ref:`cubicweb with postgresql datatabase <PostgresqlConfiguration>`
86

87
  * `cubicweb-mysql-support` contains the necessary dependencies for using
88
    :ref:`cubicweb with mysql database <MySqlConfiguration>`.
89

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

94
.. _WindowsInstallation:
95

96
97
Windows Install
---------------
98

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
101
102
103
104
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`_.
105

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

110
111
.. _python:  http://www.python.org/
.. _`The Python Package Index`: http://pypi.python.org
112

113
.. _VirtualenvInstallation:
114

115
116
`Virtualenv` install
--------------------
117

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

123
.. _PipInstallation:
124

125
126
`pip` install
-------------
127

128
129
130
131
`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
132
133
134
135

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

A working compilation chain is needed to build the modules that include C
136
extensions. If you really do not want to compile anything, installing `lxml <http://lxml.de/>`_,
Denis Laxalde's avatar
Denis Laxalde committed
137
and `libgecode <http://www.gecode.org/>`_ will help.
138

139
140
141
142
143
144
145
146
147
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
148
149
150
151
152
153
154
155
<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

Make sure to choose the correct architecture and version of Python.
156
157

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

159
160
  pip install cubicweb[pyramid]

Paul Tonelli's avatar
Paul Tonelli committed
161
Many other :ref:`cubes <AvailableCubes>` are available. A list is available at
Nicolas Chauvat's avatar
Nicolas Chauvat committed
162
163
`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

.. _EasyInstallInstallation:

171
172
`easy_install` install
----------------------
173

Nicolas Chauvat's avatar
Nicolas Chauvat committed
174
175
176
177
.. note::

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
179
180
181
182
`easy_install`_ is a python utility that helps downloading, installing, and
managing python packages and their dependencies.

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

184
  easy_install cubicweb
185

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

191
For example, installing the *blog cube* is achieved by::
192

193
  easy_install cubicweb-blog
194

195
.. note::
196

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
201
.. _`easy_install`: http://packages.python.org/distribute/easy_install.html
202
203
204


.. _SourceInstallation:
205

206
Install from source
207
-------------------
208

209
210
.. _TarballInstallation:

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

214
Make sure you also have all the :ref:`InstallDependencies`.
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.

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

228

229
.. _MercurialInstallation:
230

231
Install from version control system
232
-----------------------------------
233

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

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

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