Mercurial > kallithea

annotate 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
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
1 .. _installation:
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
2
4814
d95ea48af67b docs: rename docs/installation_win.rst to docs/installation_win_old.rst, preparing for new docs
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
3 ==========================
d95ea48af67b docs: rename docs/installation_win.rst to docs/installation_win_old.rst, preparing for new docs
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
4 Installation on Unix/Linux
d95ea48af67b docs: rename docs/installation_win.rst to docs/installation_win_old.rst, preparing for new docs
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
5 ==========================
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
6
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
7 **Kallithea** is written entirely in Python and requires Python version
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
8 2.6 or higher. Python 3.x is currently not supported.
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
9
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
10 There are several ways to install Kallithea:
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
11
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
12 - :ref:`installation-source`: The Kallithea development repository is stable
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
13 and can be used in production. In fact, the Kallithea maintainers do
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
14 use it in production. The advantage of installation from source and regularly
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
15 updating it is that you take advantage of the most recent improvements, which
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
16 is particularly useful because Kallithea is evolving rapidly.
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
17
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
18 - :ref:`installation-virtualenv`: If you prefer to only use released versions
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
19 of Kallithea, the recommended method is to install Kallithea in a virtual
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
20 Python environment using `virtualenv`. The advantages of this method over
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
21 direct installation is that Kallithea and its dependencies are completely
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
22 contained inside the virtualenv (which also means you can have multiple
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
23 installations side by side or remove it entirely by just removing the
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
24 virtualenv directory) and does not require root privileges.
4922
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
25
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
26 - :ref:`installation-without-virtualenv`: The alternative method of installing
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
27 a Kallithea release is using standard pip. The package will be installed in
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
28 the same location as all other Python packages you have ever installed. As a
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
29 result, removing it is not as straightforward as with a virtualenv, as you'd
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
30 have to remove its dependencies manually and make sure that they not are
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
31 needed by other packages.
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
32
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
33 .. _installation-source:
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
34
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
35 Installation from repository source
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
36 -----------------------------------
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
37
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
38 To install Kallithea from source in a virtualenv, follow the instructions
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
39 below::
4922
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
40
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
41 hg clone https://kallithea-scm.org/repos/kallithea
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
42 cd kallithea
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
43 virtualenv ../kallithea-venv
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
44 source ../kallithea-venv/bin/activate
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
45 python setup.py develop
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
46
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
47 You can now proceed to :ref:`setup`.
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
48
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
49 To upgrade, simply update the repository with ``hg pull -u`` and restart the
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
50 server.
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
51
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
52 .. _installation-virtualenv:
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
53
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
54 Installing a released version in a virtualenv
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
55 ---------------------------------------------
2358
69df04ee1e2b added detailed step-by-step installation instruction for windows
Marcin Kuzminski <marcin@python-works.com>
parents: 2351
diff changeset
56
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
57 It is highly recommended to use a separate virtualenv_ for installing Kallithea.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
58 This way, all libraries required by Kallithea will be installed separately from your
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
59 main Python installation and other applications and things will be less
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
60 problematic when upgrading the system or Kallithea.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
61 An additional benefit of virtualenv_ is that it doesn't require root privileges.
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
62
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
63 - Assuming you have installed virtualenv_, create a new virtual environment
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
64 in for example `/srv/kallithea/venv` using the virtualenv command::
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
65
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
66 virtualenv /srv/kallithea/venv
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
67
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
68 .. note:: Older versions of virtualenv required ``--no-site-packages`` to work
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
69 correctly. It should no longer be necessary.
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
70
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
71 - Activate the virtualenv_ in your current shell session by running::
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
72
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
73 source /srv/kallithea/venv/bin/activate
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
74
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
75 .. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
76 will "activate" a shell that terminates immediately. It is also perfectly
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
77 acceptable (and desirable) to create a virtualenv as a normal user.
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
78
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 3700
diff changeset
79 - Make a folder for Kallithea data files, and configuration somewhere on the
1309
61a6a7bf2cbd small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
80 filesystem. For example::
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
81
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
82 mkdir /srv/kallithea
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
83
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 3700
diff changeset
84 - Go into the created directory run this command to install kallithea::
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
85
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 3700
diff changeset
86 pip install kallithea
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
87
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
88 Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea,
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
89 extract it and run::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
90
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
91 python setup.py install
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
92
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 3700
diff changeset
93 - This will install Kallithea together with pylons and all other required
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
94 python libraries into the activated virtualenv.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
95
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
96 You can now proceed to :ref:`setup`.
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
97
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
98 .. _installation-without-virtualenv:
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
99
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
100 Installing a released version without virtualenv
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
101 ------------------------------------------------
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
102
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
103 For installation without virtualenv, 'just' use::
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
104
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
105 pip install kallithea
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
106
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
107 Note that this method requires root privileges and will install packages
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
108 globally without using the system's package manager.
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
109
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
110 To install as a regular user in ``~/.local``, you can use::
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
111
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
112 pip install --user kallithea
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
113
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
114 You can now proceed to :ref:`setup`.
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
115
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
116 Celery (optional)
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
117 -----------------
855
8bbe9ab76371 cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
118
1309
61a6a7bf2cbd small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
119 In order to gain maximum performance
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 3700
diff changeset
120 there are some third-party you must install. When Kallithea is used
1309
61a6a7bf2cbd small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
121 together with celery you have to install some kind of message broker,
61a6a7bf2cbd small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
122 recommended one is rabbitmq_ to make the async tasks work.
61a6a7bf2cbd small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
123
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 3700
diff changeset
124 Of course Kallithea works in sync mode also and then you do not have to install
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
125 any third party applications. However, using Celery_ will give you a large
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
126 speed improvement when using many big repositories. If you plan to use
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 3700
diff changeset
127 Kallithea for say 7 to 10 repositories, Kallithea will perform perfectly well
1309
61a6a7bf2cbd small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
128 without celery running.
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
129
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 3700
diff changeset
130 If you make the decision to run Kallithea with celery make sure you run
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
131 celeryd using paster and message broker together with the application.
1309
61a6a7bf2cbd small docs updates
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
132
855
8bbe9ab76371 cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
133 .. note::
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 3700
diff changeset
134 Installing message broker and using celery is optional, Kallithea will
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
135 work perfectly fine without them.
855
8bbe9ab76371 cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
136
8bbe9ab76371 cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
137
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
138 **Message Broker**
855
8bbe9ab76371 cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
139
8bbe9ab76371 cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
140 - preferred is `RabbitMq <http://www.rabbitmq.com/>`_
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
141 - A possible alternative is `Redis <http://code.google.com/p/redis/>`_
855
8bbe9ab76371 cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
142
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
143 For installation instructions you can visit:
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
144 http://ask.github.com/celery/getting-started/index.html.
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
145 This is a very nice tutorial on how to start using celery_ with rabbitmq_
855
8bbe9ab76371 cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
146
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
147
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
148 Next
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
149 ----
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
150
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
151 You can now proceed to :ref:`setup`.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
152
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
153
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
154 Upgrading Kallithea from Python Package Index (PyPI)
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
155 -----------------------------------------------------
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
156
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
157 .. note::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
158 Firstly, it is recommended that you **always** perform a database and
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
159 configuration backup before doing an upgrade.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
160
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
161 (These directions will use '{version}' to note that this is the version of
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
162 Kallithea that these files were used with. If backing up your Kallithea
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
163 instance from version 0.1 to 0.2, the ``my.ini`` file could be
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
164 backed up to ``my.ini.0-1``.)
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
165
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
166
4914
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4912
diff changeset
167 If using a SQLite database, stop the Kallithea process/daemon/service, and
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
168 then make a copy of the database file::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
169
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
170 service kallithea stop
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
171 cp kallithea.db kallithea.db.{version}
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
172
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
173
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
174 Back up your configuration file::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
175
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
176 cp my.ini my.ini.{version}
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
177
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
178
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
179 Ensure that you are using the Python Virtual Environment that you'd originally
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
180 installed Kallithea in::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
181
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
182 pip freeze
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
183
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
184 will list all packages installed in the current environment. If Kallithea
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
185 isn't listed, change virtual environments to your venv location::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
186
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
187 source /srv/kallithea/venv/bin/activate
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
188
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
189
4912
295900ff473d docs: don't use fixed-width fonts when not needed
Andrew Shadura <andrew@shadura.me>
parents: 4902
diff changeset
190 Once you have verified the environment you can upgrade Kallithea with::
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
191
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
192 pip install --upgrade kallithea
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
193
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
194
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
195 Then run the following command from the installation directory::
855
8bbe9ab76371 cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
196
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
197 paster make-config Kallithea my.ini
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
198
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
199 This will display any changes made by the new version of Kallithea to your
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
200 current configuration. It will try to perform an automerge. It's recommended
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
201 that you re-check the content after the automerge.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
202
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
203 .. note::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
204 Please always make sure your .ini files are up to date. Often errors are
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
205 caused by missing params added in new versions.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
206
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
207
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
208 It is also recommended that you rebuild the whoosh index after upgrading since
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
209 the new whoosh version could introduce some incompatible index changes. Please
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
210 read the changelog to see if there were any changes to whoosh.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
211
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
212
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
213 The final step is to upgrade the database. To do this simply run::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
214
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
215 paster upgrade-db my.ini
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
216
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
217 This will upgrade the schema and update some of the defaults in the database,
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
218 and will always recheck the settings of the application, if there are no new
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
219 options that need to be set.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
220
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
221
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
222 .. note::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
223 DB schema upgrade library has some limitations and can sometimes fail if you try to
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
224 upgrade from older major releases. In such case simply run upgrades sequentially, eg.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
225 upgrading from 0.1.X to 0.3.X should be done like that: 0.1.X. > 0.2.X > 0.3.X
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
226 You can always specify what version of Kallithea you want to install for example in pip
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
227 `pip install Kallithea==0.2`
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
228
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
229 You may find it helpful to clear out your log file so that new errors are
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
230 readily apparent::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
231
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
232 echo > kallithea.log
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
233
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
234 Once that is complete, you may now start your upgraded Kallithea Instance::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
235
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
236 service kallithea start
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
237
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
238 Or::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
239
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
240 paster serve /srv/kallithea/my.ini
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
241
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
242 .. note::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
243 If you're using Celery, make sure you restart all instances of it after
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
244 upgrade.
855
8bbe9ab76371 cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
245
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
246
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
247 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
248 .. _python: http://www.python.org/
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
249 .. _mercurial: http://mercurial.selenic.com/
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
250 .. _celery: http://celeryproject.org/
2806
008d9c6f7c92 fleshing out the Upgrade doc, and modified the references to Cheeseshop in the Install doc
H Waldo G <gwaldo@gmail.com>
parents: 2650
diff changeset
251 .. _rabbitmq: http://www.rabbitmq.com/