Mercurial > kallithea

comparison docs/installation.rst @ 4924:7c952ea3d7b3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs/installation: clarify and reorder alternative installation methods - Add an introduction describing the different installation methods and their pros/cons. - Clarify that Python 3.x is not currently supported. - Move standard pip install method as last method, and rename as also in virtualenv we are installing from Python Package Index.
author Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
date Sun, 15 Mar 2015 22:08:54 +0100
parents 5e66d3ec9880
children 56cd202b777e
comparison
equal deleted inserted replaced
4923:422667bdb47b 4924:7c952ea3d7b3
2 2
3 ========================== 3 ==========================
4 Installation on Unix/Linux 4 Installation on Unix/Linux
5 ========================== 5 ==========================
6 6
7 **Kallithea** is written entirely in Python. Kallithea requires Python version 7 **Kallithea** is written entirely in Python and requires Python version
8 2.6 or higher. 8 2.6 or higher. Python 3.x is currently not supported.
9 9
10 .. Note:: Alternative very detailed installation instructions for Ubuntu Server 10 There are several ways to install Kallithea:
11 with celery, indexer and daemon scripts: https://gist.github.com/4546398 11
12 12 - :ref:`installation-source`: The Kallithea development repository is stable
13 Installing Kallithea from repository source 13 and can be used in production. In fact, the Kallithea maintainers do
14 ------------------------------------------- 14 use it in production. The advantage of installation from source and regularly
15 15 updating it is that you take advantage of the most recent improvements, which
16 The Kallithea development repository is stable and can be used in production. 16 is particularly useful because Kallithea is evolving rapidly.
17 Follow these instructions:: 17
18 - :ref:`installation-virtualenv`: If you prefer to only use released versions
19 of Kallithea, the recommended method is to install Kallithea in a virtual
20 Python environment using `virtualenv`. The advantages of this method over
21 direct installation is that Kallithea and its dependencies are completely
22 contained inside the virtualenv (which also means you can have multiple
23 installations side by side or remove it entirely by just removing the
24 virtualenv directory) and does not require root privileges.
25
26 - :ref:`installation-without-virtualenv`: The alternative method of installing
27 a Kallithea release is using standard pip. The package will be installed in
28 the same location as all other Python packages you have ever installed. As a
29 result, removing it is not as straightforward as with a virtualenv, as you'd
30 have to remove its dependencies manually and make sure that they not are
31 needed by other packages.
32
33 .. _installation-source:
34
35 Installation from repository source
36 -----------------------------------
37
38 To install Kallithea from source in a virtualenv, follow the instructions
39 below::
18 40
19 hg clone https://kallithea-scm.org/repos/kallithea 41 hg clone https://kallithea-scm.org/repos/kallithea
20 cd kallithea 42 cd kallithea
21 virtualenv ../kallithea-venv 43 virtualenv ../kallithea-venv
22 source ../kallithea-venv/bin/activate 44 source ../kallithea-venv/bin/activate
25 You can now proceed to :ref:`setup`. 47 You can now proceed to :ref:`setup`.
26 48
27 To upgrade, simply update the repository with ``hg pull -u`` and restart the 49 To upgrade, simply update the repository with ``hg pull -u`` and restart the
28 server. 50 server.
29 51
30 Installing Kallithea from Python Package Index (PyPI) 52 .. _installation-virtualenv:
31 ----------------------------------------------------- 53
32 54 Installing a released version in a virtualenv
33 **Kallithea** can be installed from PyPI with:: 55 ---------------------------------------------
34
35 pip install kallithea
36
37
38 Installation in virtualenv
39 --------------------------
40 56
41 It is highly recommended to use a separate virtualenv_ for installing Kallithea. 57 It is highly recommended to use a separate virtualenv_ for installing Kallithea.
42 This way, all libraries required by Kallithea will be installed separately from your 58 This way, all libraries required by Kallithea will be installed separately from your
43 main Python installation and things will be less problematic when upgrading the 59 main Python installation and other applications and things will be less
44 system or Kallithea. 60 problematic when upgrading the system or Kallithea.
45 An additional benefit of virtualenv_ is that it doesn't require root privileges. 61 An additional benefit of virtualenv_ is that it doesn't require root privileges.
46 62
47 - Assuming you have installed virtualenv_, create a new virtual environment 63 - Assuming you have installed virtualenv_, create a new virtual environment
48 using virtualenv command:: 64 in for example `/srv/kallithea/venv` using the virtualenv command::
49 65
50 virtualenv /srv/kallithea/venv 66 virtualenv /srv/kallithea/venv
51 67
52 .. note:: Older versions of virtualenv required ``--no-site-packages`` to work 68 .. note:: Older versions of virtualenv required ``--no-site-packages`` to work
53 correctly. It should no longer be necessary. 69 correctly. It should no longer be necessary.
54 70
55 - this will install new virtualenv_ into `/srv/kallithea/venv`.
56 - Activate the virtualenv_ in your current shell session by running:: 71 - Activate the virtualenv_ in your current shell session by running::
57 72
58 source /srv/kallithea/venv/bin/activate 73 source /srv/kallithea/venv/bin/activate
59 74
60 .. note:: If you're using UNIX, *do not* use ``sudo`` to run the 75 .. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it
61 ``virtualenv`` script. It's perfectly acceptable (and desirable) 76 will "activate" a shell that terminates immediately. It is also perfectly
62 to create a virtualenv as a normal user. 77 acceptable (and desirable) to create a virtualenv as a normal user.
63 78
64 - Make a folder for Kallithea data files, and configuration somewhere on the 79 - Make a folder for Kallithea data files, and configuration somewhere on the
65 filesystem. For example:: 80 filesystem. For example::
66 81
67 mkdir /srv/kallithea 82 mkdir /srv/kallithea
76 python setup.py install 91 python setup.py install
77 92
78 - This will install Kallithea together with pylons and all other required 93 - This will install Kallithea together with pylons and all other required
79 python libraries into the activated virtualenv. 94 python libraries into the activated virtualenv.
80 95
81 96 You can now proceed to :ref:`setup`.
82 Requirements for Celery (optional) 97
83 ---------------------------------- 98 .. _installation-without-virtualenv:
99
100 Installing a released version without virtualenv
101 ------------------------------------------------
102
103 For installation without virtualenv, 'just' use::
104
105 pip install kallithea
106
107 Note that this method requires root privileges and will install packages
108 globally without using the system's package manager.
109
110 To install as a regular user in ``~/.local``, you can use::
111
112 pip install --user kallithea
113
114 You can now proceed to :ref:`setup`.
115
116 Celery (optional)
117 -----------------
84 118
85 In order to gain maximum performance 119 In order to gain maximum performance
86 there are some third-party you must install. When Kallithea is used 120 there are some third-party you must install. When Kallithea is used
87 together with celery you have to install some kind of message broker, 121 together with celery you have to install some kind of message broker,
88 recommended one is rabbitmq_ to make the async tasks work. 122 recommended one is rabbitmq_ to make the async tasks work.