##// END OF EJS Templates
docs: prepare for having a stable development branch
Mads Kiilerich -
r4989:8927a1ac default
parent child Browse files
Show More
@@ -1,209 +1,209 b''
1 .. _installation:
1 .. _installation:
2
2
3 ==========================
3 ==========================
4 Installation on Unix/Linux
4 Installation on Unix/Linux
5 ==========================
5 ==========================
6
6
7 **Kallithea** is written entirely in Python_ and requires Python version
7 **Kallithea** is written entirely in Python_ and requires Python version
8 2.6 or higher. Python 3.x is currently not supported.
8 2.6 or higher. Python 3.x is currently not supported.
9
9
10 There are several ways to install Kallithea:
10 There are several ways to install Kallithea:
11
11
12 - :ref:`installation-source`: The Kallithea development repository is stable
12 - :ref:`installation-source`: The Kallithea development repository is stable
13 and can be used in production. In fact, the Kallithea maintainers do
13 and can be used in production. In fact, the Kallithea maintainers do
14 use it in production. The advantage of installation from source and regularly
14 use it in production. The advantage of installation from source and regularly
15 updating it is that you take advantage of the most recent improvements, which
15 updating it is that you take advantage of the most recent improvements, which
16 is particularly useful because Kallithea is evolving rapidly.
16 is particularly useful because Kallithea is evolving rapidly.
17
17
18 - :ref:`installation-virtualenv`: If you prefer to only use released versions
18 - :ref:`installation-virtualenv`: If you prefer to only use released versions
19 of Kallithea, the recommended method is to install Kallithea in a virtual
19 of Kallithea, the recommended method is to install Kallithea in a virtual
20 Python environment using `virtualenv`. The advantages of this method over
20 Python environment using `virtualenv`. The advantages of this method over
21 direct installation is that Kallithea and its dependencies are completely
21 direct installation is that Kallithea and its dependencies are completely
22 contained inside the virtualenv (which also means you can have multiple
22 contained inside the virtualenv (which also means you can have multiple
23 installations side by side or remove it entirely by just removing the
23 installations side by side or remove it entirely by just removing the
24 virtualenv directory) and does not require root privileges.
24 virtualenv directory) and does not require root privileges.
25
25
26 - :ref:`installation-without-virtualenv`: The alternative method of installing
26 - :ref:`installation-without-virtualenv`: The alternative method of installing
27 a Kallithea release is using standard pip. The package will be installed in
27 a Kallithea release is using standard pip. The package will be installed in
28 the same location as all other Python packages you have ever installed. As a
28 the same location as all other Python packages you have ever installed. As a
29 result, removing it is not as straightforward as with a virtualenv, as you'd
29 result, removing it is not as straightforward as with a virtualenv, as you'd
30 have to remove its dependencies manually and make sure that they are not
30 have to remove its dependencies manually and make sure that they are not
31 needed by other packages.
31 needed by other packages.
32
32
33 .. _installation-source:
33 .. _installation-source:
34
34
35 Installation from repository source
35 Installation from repository source
36 -----------------------------------
36 -----------------------------------
37
37
38 To install Kallithea from source in a virtualenv, follow the instructions
38 To install Kallithea in a virtualenv using the stable branch of the development
39 below::
39 repository, follow the instructions below::
40
40
41 hg clone https://kallithea-scm.org/repos/kallithea
41 hg clone https://kallithea-scm.org/repos/kallithea -u stable
42 cd kallithea
42 cd kallithea
43 virtualenv ../kallithea-venv
43 virtualenv ../kallithea-venv
44 source ../kallithea-venv/bin/activate
44 source ../kallithea-venv/bin/activate
45 python setup.py develop
45 python setup.py develop
46 python setup.py compile_catalog # for translation of the UI
46 python setup.py compile_catalog # for translation of the UI
47
47
48 You can now proceed to :ref:`setup`.
48 You can now proceed to :ref:`setup`.
49
49
50 To upgrade, simply update the repository with ``hg pull -u`` and restart the
50 To upgrade, simply update the repository with ``hg pull -u`` and restart the
51 server.
51 server.
52
52
53 .. _installation-virtualenv:
53 .. _installation-virtualenv:
54
54
55 Installing a released version in a virtualenv
55 Installing a released version in a virtualenv
56 ---------------------------------------------
56 ---------------------------------------------
57
57
58 It is highly recommended to use a separate virtualenv_ for installing Kallithea.
58 It is highly recommended to use a separate virtualenv_ for installing Kallithea.
59 This way, all libraries required by Kallithea will be installed separately from your
59 This way, all libraries required by Kallithea will be installed separately from your
60 main Python installation and other applications and things will be less
60 main Python installation and other applications and things will be less
61 problematic when upgrading the system or Kallithea.
61 problematic when upgrading the system or Kallithea.
62 An additional benefit of virtualenv_ is that it doesn't require root privileges.
62 An additional benefit of virtualenv_ is that it doesn't require root privileges.
63
63
64 - Assuming you have installed virtualenv_, create a new virtual environment
64 - Assuming you have installed virtualenv_, create a new virtual environment
65 for example, in `/srv/kallithea/venv`, using the virtualenv command::
65 for example, in `/srv/kallithea/venv`, using the virtualenv command::
66
66
67 virtualenv /srv/kallithea/venv
67 virtualenv /srv/kallithea/venv
68
68
69 - Activate the virtualenv_ in your current shell session by running::
69 - Activate the virtualenv_ in your current shell session by running::
70
70
71 source /srv/kallithea/venv/bin/activate
71 source /srv/kallithea/venv/bin/activate
72
72
73 .. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it
73 .. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it
74 will "activate" a shell that terminates immediately. It is also perfectly
74 will "activate" a shell that terminates immediately. It is also perfectly
75 acceptable (and desirable) to create a virtualenv as a normal user.
75 acceptable (and desirable) to create a virtualenv as a normal user.
76
76
77 - Make a folder for Kallithea data files, and configuration somewhere on the
77 - Make a folder for Kallithea data files, and configuration somewhere on the
78 filesystem. For example::
78 filesystem. For example::
79
79
80 mkdir /srv/kallithea
80 mkdir /srv/kallithea
81
81
82 - Go into the created directory and run this command to install Kallithea::
82 - Go into the created directory and run this command to install Kallithea::
83
83
84 pip install kallithea
84 pip install kallithea
85
85
86 Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea,
86 Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea,
87 extract it and run::
87 extract it and run::
88
88
89 python setup.py install
89 python setup.py install
90
90
91 - This will install Kallithea together with pylons_ and all other required
91 - This will install Kallithea together with pylons_ and all other required
92 python libraries into the activated virtualenv.
92 python libraries into the activated virtualenv.
93
93
94 You can now proceed to :ref:`setup`.
94 You can now proceed to :ref:`setup`.
95
95
96 .. _installation-without-virtualenv:
96 .. _installation-without-virtualenv:
97
97
98 Installing a released version without virtualenv
98 Installing a released version without virtualenv
99 ------------------------------------------------
99 ------------------------------------------------
100
100
101 For installation without virtualenv, 'just' use::
101 For installation without virtualenv, 'just' use::
102
102
103 pip install kallithea
103 pip install kallithea
104
104
105 Note that this method requires root privileges and will install packages
105 Note that this method requires root privileges and will install packages
106 globally without using the system's package manager.
106 globally without using the system's package manager.
107
107
108 To install as a regular user in ``~/.local``, you can use::
108 To install as a regular user in ``~/.local``, you can use::
109
109
110 pip install --user kallithea
110 pip install --user kallithea
111
111
112 You can now proceed to :ref:`setup`.
112 You can now proceed to :ref:`setup`.
113
113
114 Upgrading Kallithea from Python Package Index (PyPI)
114 Upgrading Kallithea from Python Package Index (PyPI)
115 -----------------------------------------------------
115 -----------------------------------------------------
116
116
117 .. note::
117 .. note::
118 It is strongly recommended that you **always** perform a database and
118 It is strongly recommended that you **always** perform a database and
119 configuration backup before doing an upgrade.
119 configuration backup before doing an upgrade.
120
120
121 These directions will use '{version}' to note that this is the version of
121 These directions will use '{version}' to note that this is the version of
122 Kallithea that these files were used with. If backing up your Kallithea
122 Kallithea that these files were used with. If backing up your Kallithea
123 instance from version 0.1 to 0.2, the ``my.ini`` file could be
123 instance from version 0.1 to 0.2, the ``my.ini`` file could be
124 backed up to ``my.ini.0-1``.
124 backed up to ``my.ini.0-1``.
125
125
126
126
127 If using a SQLite database, stop the Kallithea process/daemon/service, and
127 If using a SQLite database, stop the Kallithea process/daemon/service, and
128 then make a copy of the database file::
128 then make a copy of the database file::
129
129
130 service kallithea stop
130 service kallithea stop
131 cp kallithea.db kallithea.db.{version}
131 cp kallithea.db kallithea.db.{version}
132
132
133
133
134 Back up your configuration file::
134 Back up your configuration file::
135
135
136 cp my.ini my.ini.{version}
136 cp my.ini my.ini.{version}
137
137
138
138
139 Ensure that you are using the Python virtual environment that you originally
139 Ensure that you are using the Python virtual environment that you originally
140 installed Kallithea in by running::
140 installed Kallithea in by running::
141
141
142 pip freeze
142 pip freeze
143
143
144 This will list all packages installed in the current environment. If
144 This will list all packages installed in the current environment. If
145 Kallithea isn't listed, activate the correct virtual environment::
145 Kallithea isn't listed, activate the correct virtual environment::
146
146
147 source /srv/kallithea/venv/bin/activate
147 source /srv/kallithea/venv/bin/activate
148
148
149
149
150 Once you have verified the environment you can upgrade Kallithea with::
150 Once you have verified the environment you can upgrade Kallithea with::
151
151
152 pip install --upgrade kallithea
152 pip install --upgrade kallithea
153
153
154
154
155 Then run the following command from the installation directory::
155 Then run the following command from the installation directory::
156
156
157 paster make-config Kallithea my.ini
157 paster make-config Kallithea my.ini
158
158
159 This will display any changes made by the new version of Kallithea to your
159 This will display any changes made by the new version of Kallithea to your
160 current configuration. It will try to perform an automerge. It is recommended
160 current configuration. It will try to perform an automerge. It is recommended
161 that you recheck the content after the automerge.
161 that you recheck the content after the automerge.
162
162
163 .. note::
163 .. note::
164 Please always make sure your .ini files are up to date. Errors can
164 Please always make sure your .ini files are up to date. Errors can
165 often be caused by missing parameters added in new versions.
165 often be caused by missing parameters added in new versions.
166
166
167
167
168 It is also recommended that you rebuild the whoosh index after upgrading since
168 It is also recommended that you rebuild the whoosh index after upgrading since
169 the new whoosh version could introduce some incompatible index changes. Please
169 the new whoosh version could introduce some incompatible index changes. Please
170 read the changelog to see if there were any changes to whoosh.
170 read the changelog to see if there were any changes to whoosh.
171
171
172
172
173 The final step is to upgrade the database. To do this simply run::
173 The final step is to upgrade the database. To do this simply run::
174
174
175 paster upgrade-db my.ini
175 paster upgrade-db my.ini
176
176
177 This will upgrade the schema and update some of the defaults in the database,
177 This will upgrade the schema and update some of the defaults in the database,
178 and will always recheck the settings of the application, if there are no new
178 and will always recheck the settings of the application, if there are no new
179 options that need to be set.
179 options that need to be set.
180
180
181
181
182 .. note::
182 .. note::
183 The DB schema upgrade library has some limitations and can sometimes fail if you try to
183 The DB schema upgrade library has some limitations and can sometimes fail if you try to
184 upgrade from older major releases. In such a case simply run upgrades sequentially, e.g.,
184 upgrade from older major releases. In such a case simply run upgrades sequentially, e.g.,
185 upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X
185 upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X
186 You can always specify what version of Kallithea you want to install for example in pip
186 You can always specify what version of Kallithea you want to install for example in pip
187 `pip install Kallithea==0.2`
187 `pip install Kallithea==0.2`
188
188
189 You may find it helpful to clear out your log file so that new errors are
189 You may find it helpful to clear out your log file so that new errors are
190 readily apparent::
190 readily apparent::
191
191
192 echo > kallithea.log
192 echo > kallithea.log
193
193
194 Once that is complete, you may now start your upgraded Kallithea Instance::
194 Once that is complete, you may now start your upgraded Kallithea Instance::
195
195
196 service kallithea start
196 service kallithea start
197
197
198 Or::
198 Or::
199
199
200 paster serve /srv/kallithea/my.ini
200 paster serve /srv/kallithea/my.ini
201
201
202 .. note::
202 .. note::
203 If you're using Celery, make sure you restart all instances of it after
203 If you're using Celery, make sure you restart all instances of it after
204 upgrade.
204 upgrade.
205
205
206
206
207 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
207 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
208 .. _Python: http://www.python.org/
208 .. _Python: http://www.python.org/
209 .. _pylons: http://www.pylonsproject.org/
209 .. _pylons: http://www.pylonsproject.org/
General Comments 0
You need to be logged in to leave comments. Login now