setup.rst 7.19 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
- `Installation on Debian/Ubuntu`_
- `Installation in a virtualenv`_
- `Installation with pip`_
- `Installation with easy_install`_
- `Installation from tarball`_
23

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

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

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

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

38

39
40
.. _DebianInstallation:

41
42
43
44
Debian/Ubuntu install
---------------------

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

49
Depending on the distribution you are using, add the appropriate line to your
50
51
`list of sources` (for example by editing ``/etc/apt/sources.list``), replacing
``<release>`` with e.g. ``wheezy`` or ``trusty``::
52

53
  deb http://download.logilab.org/production/ <release>/
54

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

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

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
62
  apt-get update
63
  apt-get install python3-cubicweb --install-recommends
64

65
66
67
``python3-cubicweb`` installs the framework itself, allowing you to create new
instances. Installing recommended packages will install the development
environment allowing you to develop new cubes.
68

Nicolas Chauvat's avatar
Nicolas Chauvat committed
69
70
71
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`_.
72

73
74
.. note::

75
  `python3-cubicweb` will install basic sqlite support. You can easily setup
Nicolas Chauvat's avatar
Nicolas Chauvat committed
76
77
  :ref:`cubicweb with other database <DatabaseInstallation>` using the following
  virtual packages :
78

79
  * `python3-cubicweb-postgresql-support` contains the necessary dependencies for
80
    using :ref:`cubicweb with postgresql datatabase <PostgresqlConfiguration>`
81

82
.. _`list of sources`: http://wiki.debian.org/SourcesList
83
.. _`Logilab's gnupg key`: https://www.logilab.fr/logilab-debian-keyring.gpg
84
85
.. _`CubicWeb.org Forge`: http://www.cubicweb.org/project/

86
.. _VirtualenvInstallation:
87

88
89
`Virtualenv` install
--------------------
90

91
92
93
94
|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.
95

96
.. _PipInstallation:
97

98
99
`pip` install
-------------
100

101
102
103
104
`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
105
106
107
108

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

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

112
113
114
115
116
117
118
119
120
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
121
122
123
124
125
126
127
128
<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.
129
130

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

132
133
  pip install cubicweb[pyramid]

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

138
139
140
For example, installing the *blog cube* is achieved by::

  pip install cubicweb-blog
141
142
143

.. _EasyInstallInstallation:

144
145
`easy_install` install
----------------------
146

Nicolas Chauvat's avatar
Nicolas Chauvat committed
147
148
149
150
.. note::

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
152
153
154
155
`easy_install`_ is a python utility that helps downloading, installing, and
managing python packages and their dependencies.

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

157
  easy_install cubicweb
158

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

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

166
  easy_install cubicweb-blog
167

168
.. note::
169

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
174
.. _`easy_install`: http://packages.python.org/distribute/easy_install.html
175
176
177


.. _SourceInstallation:
178

179
Install from source
180
-------------------
181

182
183
.. _TarballInstallation:

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

187
Make sure you also have all the :ref:`InstallDependencies`.
188

189
190
191
192
193
194
195
196
197
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
198
There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can access a
199
list of availble cubes at the `CubicWeb.org Forge`_.
200

201

202
.. _MercurialInstallation:
203

204
Install from version control system
205
-----------------------------------
206

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

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

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