Mercurial > kallithea

annotate docs/installation.rst @ 5778:64e2d5a291a7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
settings: rescope 'Analytics HTML' option to generic HTML/JS/CSS customization Update the setting name 'Analytics HTML block' to better cover the fact that it can be used to make any HTML, JavaScript or CSS tweak.
author Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
date Mon, 14 Mar 2016 22:12:28 +0100
parents 250f8150c4bb
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/