Mercurial > kallithea

annotate docs/installation.rst @ 5755:250f8150c4bb stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: suggest using pip instead of setup.py develop
author Andrew Shadura <andrew@shadura.me>
date Sat, 12 Mar 2016 14:35:43 +0100
parents 4e9f5ef98dc4
children 8075ec3d0233 b777b096d9a2
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
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
7 The following describes three different ways of installing Kallithea:
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
8
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents: 4989
diff changeset
9 - :ref:`installation-source`: The simplest way to keep the installation
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
10 up-to-date and track any local customizations is to run directly from
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
11 source in a Kallithea repository clone, preferably inside a virtualenv
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
12 virtual Python environment.
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
13
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
14 - :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
15 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
16 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
17 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
18 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
19 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
20 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
21
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
22 - :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
23 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
24 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
25 result, removing it is not as straightforward as with a virtualenv, as you'd
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
26 have to remove its dependencies manually and make sure that they are not
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
27 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
28
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
29 .. _installation-source:
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
30
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5425
diff changeset
31
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
32 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
33 -----------------------------------
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
34
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
35 To install Kallithea in a virtualenv_ using the stable branch of the development
4989
8927a1ac8d41 docs: prepare for having a stable development branch
Mads Kiilerich <madski@unity3d.com>
parents: 4986
diff changeset
36 repository, follow the instructions below::
4922
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
37
4989
8927a1ac8d41 docs: prepare for having a stable development branch
Mads Kiilerich <madski@unity3d.com>
parents: 4986
diff changeset
38 hg clone https://kallithea-scm.org/repos/kallithea -u stable
4922
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
39 cd kallithea
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
40 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
41 source ../kallithea-venv/bin/activate
5519
8c234ae2c258 docs: add advice of upgrading pip and setuptools in new virtualenvs
Mads Kiilerich <madski@unity3d.com>
parents: 5502
diff changeset
42 pip install --upgrade pip setuptools
5755
250f8150c4bb docs: suggest using pip instead of setup.py develop
Andrew Shadura <andrew@shadura.me>
parents: 5520
diff changeset
43 pip install -e .
5502
ae9ab4c92d46 setup: explicitly use python2 in examples in the documentation
Mads Kiilerich <madski@unity3d.com>
parents: 5434
diff changeset
44 python2 setup.py compile_catalog # for translation of the UI
4922
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
45
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
46 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
47
5e66d3ec9880 docs/installation: add section on installation from repository source
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
48 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
49 server.
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
50
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
51 .. _installation-virtualenv:
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
52
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5425
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.
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
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
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
64 for example, in `/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
5519
8c234ae2c258 docs: add advice of upgrading pip and setuptools in new virtualenvs
Mads Kiilerich <madski@unity3d.com>
parents: 5502
diff changeset
68 - Activate the virtualenv_ in your current shell session and make sure the
8c234ae2c258 docs: add advice of upgrading pip and setuptools in new virtualenvs
Mads Kiilerich <madski@unity3d.com>
parents: 5502
diff changeset
69 basic requirements are up-to-date by running::
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 source /srv/kallithea/venv/bin/activate
5519
8c234ae2c258 docs: add advice of upgrading pip and setuptools in new virtualenvs
Mads Kiilerich <madski@unity3d.com>
parents: 5502
diff changeset
72 pip install --upgrade pip setuptools
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
73
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
74 .. 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
75 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
76 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
77
5520
4e9f5ef98dc4 docs: mention that the optional dependencies psycopg2 and python-ldap also might be needed in the virtualenv
Mads Kiilerich <madski@unity3d.com>
parents: 5519
diff changeset
78 .. note:: Some dependencies are optional. If you need them, install them in
4e9f5ef98dc4 docs: mention that the optional dependencies psycopg2 and python-ldap also might be needed in the virtualenv
Mads Kiilerich <madski@unity3d.com>
parents: 5519
diff changeset
79 the virtualenv too::
4e9f5ef98dc4 docs: mention that the optional dependencies psycopg2 and python-ldap also might be needed in the virtualenv
Mads Kiilerich <madski@unity3d.com>
parents: 5519
diff changeset
80
4e9f5ef98dc4 docs: mention that the optional dependencies psycopg2 and python-ldap also might be needed in the virtualenv
Mads Kiilerich <madski@unity3d.com>
parents: 5519
diff changeset
81 pip install psycopg2
4e9f5ef98dc4 docs: mention that the optional dependencies psycopg2 and python-ldap also might be needed in the virtualenv
Mads Kiilerich <madski@unity3d.com>
parents: 5519
diff changeset
82 pip install python-ldap
4e9f5ef98dc4 docs: mention that the optional dependencies psycopg2 and python-ldap also might be needed in the virtualenv
Mads Kiilerich <madski@unity3d.com>
parents: 5519
diff changeset
83
4e9f5ef98dc4 docs: mention that the optional dependencies psycopg2 and python-ldap also might be needed in the virtualenv
Mads Kiilerich <madski@unity3d.com>
parents: 5519
diff changeset
84 This might require installation of development packages using your
4e9f5ef98dc4 docs: mention that the optional dependencies psycopg2 and python-ldap also might be needed in the virtualenv
Mads Kiilerich <madski@unity3d.com>
parents: 5519
diff changeset
85 distribution's package manager.
4e9f5ef98dc4 docs: mention that the optional dependencies psycopg2 and python-ldap also might be needed in the virtualenv
Mads Kiilerich <madski@unity3d.com>
parents: 5519
diff changeset
86
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 3700
diff changeset
87 - 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
88 filesystem. For example::
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
89
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
90 mkdir /srv/kallithea
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
91
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
92 - Go into the created directory and run this command to install Kallithea::
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
93
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 3700
diff changeset
94 pip install kallithea
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
95
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
96 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
97 extract it and run::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
98
5755
250f8150c4bb docs: suggest using pip instead of setup.py develop
Andrew Shadura <andrew@shadura.me>
parents: 5520
diff changeset
99 pip install .
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
100
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
101 - 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
102 python libraries into the activated virtualenv.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
103
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
104 You can now proceed to :ref:`setup`.
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
105
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
106 .. _installation-without-virtualenv:
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
107
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5425
diff changeset
108
4924
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
109 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
110 ------------------------------------------------
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 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
113
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
114 pip install kallithea
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 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
117 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
118
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
119 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
120
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
121 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
122
7c952ea3d7b3 docs/installation: clarify and reorder alternative installation methods
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4922
diff changeset
123 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
124
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5425
diff changeset
125
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
126 Upgrading Kallithea from Python Package Index (PyPI)
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5081
diff changeset
127 ----------------------------------------------------
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
128
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
129 .. note::
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
130 It is strongly recommended that you **always** perform a database and
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
131 configuration backup before doing an upgrade.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
132
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
133 These directions will use '{version}' to note that this is the version of
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
134 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
135 instance from version 0.1 to 0.2, the ``my.ini`` file could be
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
136 backed up to ``my.ini.0-1``.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
137
4914
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4912
diff changeset
138 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
139 then make a copy of the database file::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
140
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
141 service kallithea stop
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
142 cp kallithea.db kallithea.db.{version}
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
143
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
144 Back up your configuration file::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
145
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
146 cp my.ini my.ini.{version}
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
147
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
148 Ensure that you are using the Python virtual environment that you originally
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
149 installed Kallithea in by running::
4902
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 pip freeze
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
152
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
153 This will list all packages installed in the current environment. If
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
154 Kallithea isn't listed, activate the correct virtual environment::
4902
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 source /srv/kallithea/venv/bin/activate
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
157
4912
295900ff473d docs: don't use fixed-width fonts when not needed
Andrew Shadura <andrew@shadura.me>
parents: 4902
diff changeset
158 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
159
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
160 pip install --upgrade kallithea
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
161
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
162 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
163
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
164 paster make-config Kallithea my.ini
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 This will display any changes made by the new version of Kallithea to your
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
167 current configuration. It will try to perform an automerge. It is recommended
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
168 that you recheck the content after the automerge.
4902
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 .. note::
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
171 Please always make sure your .ini files are up to date. Errors can
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
172 often be caused by missing parameters added in new versions.
4902
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 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
175 the new whoosh version could introduce some incompatible index changes. Please
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
176 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
177
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
178 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
179
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
180 paster upgrade-db my.ini
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 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
183 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
184 options that need to be set.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
185
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
186 .. note::
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
187 The DB schema upgrade library has some limitations and can sometimes fail if you try to
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
188 upgrade from older major releases. In such a case simply run upgrades sequentially, e.g.,
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
189 upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
190 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
191 `pip install Kallithea==0.2`
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
192
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
193 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
194 readily apparent::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
195
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
196 echo > kallithea.log
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
197
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
198 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
199
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
200 service kallithea start
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
201
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
202 Or::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
203
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
204 paster serve /srv/kallithea/my.ini
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
205
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
206 .. note::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4814
diff changeset
207 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
208 upgrade.
855
8bbe9ab76371 cleaned installation docs a little
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
209
568
5f481e4e888b updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
210
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 3169
diff changeset
211 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
4955
4e6dfdb3fa01 docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents: 4925
diff changeset
212 .. _pylons: http://www.pylonsproject.org/