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

18
- `Installation using docker`_
Nicolas Chauvat's avatar
Nicolas Chauvat committed
19
20
21
22
23
- `Installation on Debian/Ubuntu`_
- `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
and advanced features of |cubicweb|.

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

39

40
41
42
43
44
45
46
47
48
49
50
51
.. _DockerInstallation:

Docker install
--------------

Detailed instructions on how to deploy CubicWeb using docker can be found
on the `docker hub <https://hub.docker.com/r/logilab/cubicweb>`_.

The images there are built using the following source code :
`docker-cubicweb <https://hg.logilab.org/master/docker-cubicweb/>`_,
see it's `README <https://hg.logilab.org/master/docker-cubicweb/file/tip/README.rst>`_

52
53
.. _DebianInstallation:

54
55
56
57
Debian/Ubuntu install
---------------------

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

62
Depending on the distribution you are using, add the appropriate line to your
63
`list of sources` (for example by editing ``/etc/apt/sources.list``), replacing
64
``<release>`` with e.g. ``buster`` or ``bionic``::
65

66
67
  deb http://apt.logilab.fr <release> main  # all cubicweb & cubes
  deb http://apt.logilab.fr <release> cubicweb-3.26  # latest cubicweb 3.26 & cubes
68

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

72
  wget -O/etc/apt/trusted.gpg.d/logilab.gpg https://www.logilab.fr/logilab-debian-keyring.gpg
73
74

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
76
  apt-get update
77
  apt-get install python3-cubicweb --install-recommends
78

79
80
81
``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.
82

Nicolas Chauvat's avatar
Nicolas Chauvat committed
83
84
85
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`_.
86

87
88
.. note::

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

93
  * `python3-cubicweb-postgresql-support` contains the necessary dependencies for
94
    using :ref:`cubicweb with postgresql datatabase <PostgresqlConfiguration>`
95

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

100
.. _VirtualenvInstallation:
101

102
103
`Virtualenv` install
--------------------
104

105
106
107
108
|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.
109

110
.. _PipInstallation:
111

112
113
`pip` install
-------------
114

115
116
117
118
`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
119
120
121
122

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

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

126
127
128
129
130
131
132
133
134
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
135
136
137
138
139
140
141
142
<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.
143
144

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

146
147
  pip install cubicweb[pyramid]

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

152
153
154
For example, installing the *blog cube* is achieved by::

  pip install cubicweb-blog
155
156
157

.. _EasyInstallInstallation:

158
159
`easy_install` install
----------------------
160

Nicolas Chauvat's avatar
Nicolas Chauvat committed
161
162
163
164
.. note::

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
166
167
168
169
`easy_install`_ is a python utility that helps downloading, installing, and
managing python packages and their dependencies.

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

171
  easy_install cubicweb
172

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

178
For example, installing the *blog cube* is achieved by::
179

180
  easy_install cubicweb-blog
181

182
.. note::
183

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

Nicolas Chauvat's avatar
Nicolas Chauvat committed
188
.. _`easy_install`: http://packages.python.org/distribute/easy_install.html
189
190
191


.. _SourceInstallation:
192

193
Install from source
194
-------------------
195

196
197
.. _TarballInstallation:

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

201
Make sure you also have all the :ref:`InstallDependencies`.
202

203
204
205
206
207
208
209
210
211
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
212
There is also a wide variety of :ref:`cubes <AvailableCubes>`. You can access a
213
list of availble cubes at the `CubicWeb.org Forge`_.
214

215

216
.. _MercurialInstallation:
217

218
Install from version control system
219
-----------------------------------
220

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

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

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