Mercurial > kallithea

comparison docs/installation.rst @ 5477:6f60bd9090b1 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
release: merge default to stable for 0.3
author Mads Kiilerich <madski@unity3d.com>
date Sun, 06 Sep 2015 23:36:05 +0200
parents 8867673c8192
children ae9ab4c92d46
comparison
equal deleted inserted replaced
5267:763dc7a96bae 5477:6f60bd9090b1
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 The following describes three different ways of installing Kallithea:
8 2.6 or higher. Python 3.x is currently not supported. 8
9 9 - :ref:`installation-source`: The simplest way to keep the installation
10 There are several ways to install Kallithea: 10 up-to-date and track any local customizations is to run directly from
11 11 source in a Kallithea repository clone, preferably inside a virtualenv
12 - :ref:`installation-source`: The Kallithea development repository is stable 12 virtual Python environment.
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
15 updating it is that you take advantage of the most recent improvements, which
16 is particularly useful because Kallithea is evolving rapidly.
17 13
18 - :ref:`installation-virtualenv`: If you prefer to only use released versions 14 - :ref:`installation-virtualenv`: If you prefer to only use released versions
19 of Kallithea, the recommended method is to install Kallithea in a virtual 15 of Kallithea, the recommended method is to install Kallithea in a virtual
20 Python environment using `virtualenv`. The advantages of this method over 16 Python environment using `virtualenv`. The advantages of this method over
21 direct installation is that Kallithea and its dependencies are completely 17 direct installation is that Kallithea and its dependencies are completely
30 have to remove its dependencies manually and make sure that they are not 26 have to remove its dependencies manually and make sure that they are not
31 needed by other packages. 27 needed by other packages.
32 28
33 .. _installation-source: 29 .. _installation-source:
34 30
31
35 Installation from repository source 32 Installation from repository source
36 ----------------------------------- 33 -----------------------------------
37 34
38 To install Kallithea in a virtualenv using the stable branch of the development 35 To install Kallithea in a virtualenv_ using the stable branch of the development
39 repository, follow the instructions below:: 36 repository, follow the instructions below::
40 37
41 hg clone https://kallithea-scm.org/repos/kallithea -u stable 38 hg clone https://kallithea-scm.org/repos/kallithea -u stable
42 cd kallithea 39 cd kallithea
43 virtualenv ../kallithea-venv 40 virtualenv ../kallithea-venv
50 To upgrade, simply update the repository with ``hg pull -u`` and restart the 47 To upgrade, simply update the repository with ``hg pull -u`` and restart the
51 server. 48 server.
52 49
53 .. _installation-virtualenv: 50 .. _installation-virtualenv:
54 51
52
55 Installing a released version in a virtualenv 53 Installing a released version in a virtualenv
56 --------------------------------------------- 54 ---------------------------------------------
57 55
58 It is highly recommended to use a separate virtualenv_ for installing Kallithea. 56 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 57 This way, all libraries required by Kallithea will be installed separately from your
93 91
94 You can now proceed to :ref:`setup`. 92 You can now proceed to :ref:`setup`.
95 93
96 .. _installation-without-virtualenv: 94 .. _installation-without-virtualenv:
97 95
96
98 Installing a released version without virtualenv 97 Installing a released version without virtualenv
99 ------------------------------------------------ 98 ------------------------------------------------
100 99
101 For installation without virtualenv, 'just' use:: 100 For installation without virtualenv, 'just' use::
102 101
109 108
110 pip install --user kallithea 109 pip install --user kallithea
111 110
112 You can now proceed to :ref:`setup`. 111 You can now proceed to :ref:`setup`.
113 112
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
127 If using a SQLite database, stop the Kallithea process/daemon/service, and 126 If using a SQLite database, stop the Kallithea process/daemon/service, and
128 then make a copy of the database file:: 127 then make a copy of the database file::
129 128
130 service kallithea stop 129 service kallithea stop
131 cp kallithea.db kallithea.db.{version} 130 cp kallithea.db kallithea.db.{version}
132 131
133
134 Back up your configuration file:: 132 Back up your configuration file::
135 133
136 cp my.ini my.ini.{version} 134 cp my.ini my.ini.{version}
137
138 135
139 Ensure that you are using the Python virtual environment that you originally 136 Ensure that you are using the Python virtual environment that you originally
140 installed Kallithea in by running:: 137 installed Kallithea in by running::
141 138
142 pip freeze 139 pip freeze
144 This will list all packages installed in the current environment. If 141 This will list all packages installed in the current environment. If
145 Kallithea isn't listed, activate the correct virtual environment:: 142 Kallithea isn't listed, activate the correct virtual environment::
146 143
147 source /srv/kallithea/venv/bin/activate 144 source /srv/kallithea/venv/bin/activate
148 145
149
150 Once you have verified the environment you can upgrade Kallithea with:: 146 Once you have verified the environment you can upgrade Kallithea with::
151 147
152 pip install --upgrade kallithea 148 pip install --upgrade kallithea
153
154 149
155 Then run the following command from the installation directory:: 150 Then run the following command from the installation directory::
156 151
157 paster make-config Kallithea my.ini 152 paster make-config Kallithea my.ini
158 153
162 157
163 .. note:: 158 .. note::
164 Please always make sure your .ini files are up to date. Errors can 159 Please always make sure your .ini files are up to date. Errors can
165 often be caused by missing parameters added in new versions. 160 often be caused by missing parameters added in new versions.
166 161
167
168 It is also recommended that you rebuild the whoosh index after upgrading since 162 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 163 the new whoosh version could introduce some incompatible index changes. Please
170 read the changelog to see if there were any changes to whoosh. 164 read the changelog to see if there were any changes to whoosh.
171 165
172
173 The final step is to upgrade the database. To do this simply run:: 166 The final step is to upgrade the database. To do this simply run::
174 167
175 paster upgrade-db my.ini 168 paster upgrade-db my.ini
176 169
177 This will upgrade the schema and update some of the defaults in the database, 170 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 171 and will always recheck the settings of the application, if there are no new
179 options that need to be set. 172 options that need to be set.
180
181 173
182 .. note:: 174 .. note::
183 The DB schema upgrade library has some limitations and can sometimes fail if you try to 175 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., 176 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 177 upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X
203 If you're using Celery, make sure you restart all instances of it after 195 If you're using Celery, make sure you restart all instances of it after
204 upgrade. 196 upgrade.
205 197
206 198
207 .. _virtualenv: http://pypi.python.org/pypi/virtualenv 199 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
208 .. _Python: http://www.python.org/
209 .. _pylons: http://www.pylonsproject.org/ 200 .. _pylons: http://www.pylonsproject.org/