Mercurial > kallithea

annotate docs/upgrade.rst @ 8829:01cb988e82a5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
celery: celery-run should only initialize app and sqlalchemy after workers have been forked If app and SqlAlchemy were initialized before launching celery, the forked workers would inherit the database connection ... and that doesn't work. This could be handled by disposing the engine after forking the worker or before each task ... but it remains unnecessary and wrong to initialize the engine early when it isn't used, and then fork it.
author Mads Kiilerich <mads@kiilerich.com>
date Fri, 01 Jan 2021 18:04:16 +0100
parents 92894fccc615
children d8e65780dbe9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
1 .. _upgrade:
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
2
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
3 ===================
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
4 Upgrading Kallithea
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
5 ===================
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
6
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
7 This describes the process for upgrading Kallithea, independently of the
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
8 Kallithea installation method.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
9
6013
0b6d2ca7175f db: drop RhodeCode compatibility (database rebranding etc.)
Søren Løvborg <sorenl@unity3d.com>
parents: 5954
diff changeset
10 .. note::
0b6d2ca7175f db: drop RhodeCode compatibility (database rebranding etc.)
Søren Løvborg <sorenl@unity3d.com>
parents: 5954
diff changeset
11 If you are upgrading from a RhodeCode installation, you must first
0b6d2ca7175f db: drop RhodeCode compatibility (database rebranding etc.)
Søren Løvborg <sorenl@unity3d.com>
parents: 5954
diff changeset
12 install Kallithea 0.3.2 and follow the instructions in the 0.3.2
0b6d2ca7175f db: drop RhodeCode compatibility (database rebranding etc.)
Søren Løvborg <sorenl@unity3d.com>
parents: 5954
diff changeset
13 README to perform a one-time conversion of the database from
0b6d2ca7175f db: drop RhodeCode compatibility (database rebranding etc.)
Søren Løvborg <sorenl@unity3d.com>
parents: 5954
diff changeset
14 RhodeCode to Kallithea, before upgrading to the latest version
0b6d2ca7175f db: drop RhodeCode compatibility (database rebranding etc.)
Søren Løvborg <sorenl@unity3d.com>
parents: 5954
diff changeset
15 of Kallithea.
0b6d2ca7175f db: drop RhodeCode compatibility (database rebranding etc.)
Søren Løvborg <sorenl@unity3d.com>
parents: 5954
diff changeset
16
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
17
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
18 1. Stop the Kallithea web application
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
19 -------------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
20
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
21 This step depends entirely on the web server software used to serve
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
22 Kallithea, but in any case, Kallithea should not be running during
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
23 the upgrade.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
24
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
25 .. note::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
26 If you're using Celery, make sure you stop all instances during the
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
27 upgrade.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
28
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
29
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
30 2. Create a backup of both database and configuration
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
31 -----------------------------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
32
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
33 You are of course strongly recommended to make backups regularly, but it
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
34 is *especially* important to make a full database and configuration
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
35 backup before performing a Kallithea upgrade.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
36
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
37 Back up your configuration
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
38 ^^^^^^^^^^^^^^^^^^^^^^^^^^
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
39
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
40 Make a copy of your Kallithea configuration (``.ini``) file.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
41
8655
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 8443
diff changeset
42 If you are using custom :ref:`extensions <customization>`, you should also
e3d8f4bc3ce7 extensions: rename 'rcextensions' into 'extensions' but provide compatibility
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 8443
diff changeset
43 make a copy of the ``extensions.py`` file.
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
44
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
45 Back up your database
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
46 ^^^^^^^^^^^^^^^^^^^^^
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
47
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
48 If using SQLite, simply make a copy of the Kallithea database (``.db``)
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
49 file.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
50
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
51 If using PostgreSQL, please consult the documentation for the ``pg_dump``
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
52 utility.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
53
8443
b688a2a1b189 docs: clarify that MariaDB is supported, with slight preference for this more free option
Mads Kiilerich <mads@kiilerich.com>
parents: 8193
diff changeset
54 If using MariaDB/MySQL, please consult the documentation for the ``mysqldump``
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
55 utility.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
56
6214
f973b866fffc Turbogears2 migration: use sqlalchemy.url iso sqlalchemy.db1.url
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6023
diff changeset
57 Look for ``sqlalchemy.url`` in your configuration file to determine
7494
874ed3e58579 docs: upgrade: misc. clarification on upgrade from 0.3.x to 0.4
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7493
diff changeset
58 database type, settings, location, etc. If you were running Kallithea 0.3.x or
874ed3e58579 docs: upgrade: misc. clarification on upgrade from 0.3.x to 0.4
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7493
diff changeset
59 older, this was ``sqlalchemy.db1.url``.
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
60
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
61
7590
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
62 3. Activate or recreate the Kallithea virtual environment (if any)
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
63 ------------------------------------------------------------------
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
64
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
65 .. note::
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
66 If you did not install Kallithea in a virtual environment, skip this step.
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
67
7590
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
68 For major upgrades, e.g. from 0.3.x to 0.4.x, it is recommended to create a new
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
69 virtual environment, rather than reusing the old. For minor upgrades, e.g.
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
70 within the 0.4.x range, this is not really necessary (but equally fine).
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
71
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
72 To create a new virtual environment, please refer to the appropriate
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
73 installation page for details. After creating and activating the new virtual
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
74 environment, proceed with the rest of the upgrade process starting from the next
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
75 section.
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
76
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
77 To reuse the same virtual environment, first activate it, then verify that you
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
78 are using the correct environment by running::
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
79
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
80 pip freeze
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
81
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
82 This will list all packages installed in the current environment. If
7590
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
83 Kallithea isn't listed, deactivate the environment and then activate the correct
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
84 one, or recreate a new environment. See the appropriate installation page for
de92f48c1375 docs: suggest creating a new virtual environment for major upgrades
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7494
diff changeset
85 details.
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
86
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
87
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
88 4. Install new version of Kallithea
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
89 -----------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
90
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
91 Please refer to the instructions for the installation method you
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
92 originally used to install Kallithea.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
93
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
94 If you originally installed using pip, it is as simple as::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
95
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
96 pip install --upgrade kallithea
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
97
7491
634c2fa427e8 docs: upgrade: make upgrade instructions from version control more explicit
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7490
diff changeset
98 If you originally installed from version control, assuming you did not make
634c2fa427e8 docs: upgrade: make upgrade instructions from version control more explicit
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7490
diff changeset
99 private changes (in which case you should adapt the instructions accordingly)::
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
100
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
101 cd my-kallithea-clone
7491
634c2fa427e8 docs: upgrade: make upgrade instructions from version control more explicit
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7490
diff changeset
102 hg parent # make a note of the original revision
634c2fa427e8 docs: upgrade: make upgrade instructions from version control more explicit
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7490
diff changeset
103 hg pull
634c2fa427e8 docs: upgrade: make upgrade instructions from version control more explicit
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7490
diff changeset
104 hg update
634c2fa427e8 docs: upgrade: make upgrade instructions from version control more explicit
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7490
diff changeset
105 hg parent # make a note of the new revision
6748
29e9cb56f26f docs: recommend --upgrade for all pip installations in a virtualenv
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
106 pip install --upgrade -e .
7055
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea
domruf <dominikruf@gmail.com>
parents: 6748
diff changeset
107
7490
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
108 .. _upgrade_config:
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
109
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
110
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
111 5. Upgrade your configuration
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
112 -----------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
113
6555
213085032127 gearbox: make a make-config sub-command available again
Mads Kiilerich <madski@unity3d.com>
parents: 6554
diff changeset
114 Run the following command to create a new configuration (``.ini``) file::
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
115
7406
7784a1212471 cli: convert 'gearbox make-config' into 'kallithea-cli config-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7378
diff changeset
116 kallithea-cli config-create new.ini
6555
213085032127 gearbox: make a make-config sub-command available again
Mads Kiilerich <madski@unity3d.com>
parents: 6554
diff changeset
117
7494
874ed3e58579 docs: upgrade: misc. clarification on upgrade from 0.3.x to 0.4
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7493
diff changeset
118 Then compare it with your old config file and copy over the required
874ed3e58579 docs: upgrade: misc. clarification on upgrade from 0.3.x to 0.4
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7493
diff changeset
119 configuration values from the old to the new file.
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
120
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
121 .. note::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
122 Please always make sure your ``.ini`` files are up to date. Errors
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
123 can often be caused by missing parameters added in new versions.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
124
6023
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
125 .. _upgrade_db:
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
126
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
127
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
128 6. Upgrade your database
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
129 ------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
130
6023
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
131 .. note::
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
132 If you are *downgrading* Kallithea, you should perform the database
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
133 migration step *before* installing the older version. (That is,
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
134 always perform migrations using the most recent of the two versions
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
135 you're migrating between.)
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
136
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
137 First, run the following command to see your current database version::
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
138
7490
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
139 alembic -c new.ini current
6023
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
140
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
141 Typical output will be something like "9358dc3d6828 (head)", which is
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
142 the current Alembic database "revision ID". Write down the entire output
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
143 for troubleshooting purposes.
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
144
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
145 The output will be empty if you're upgrading from Kallithea 0.3.x or
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
146 older. That's expected. If you get an error that the config file was not
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
147 found or has no ``[alembic]`` section, see the next section.
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
148
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
149 Next, if you are performing an *upgrade*: Run the following command to
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
150 upgrade your database to the current Kallithea version::
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
151
7490
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
152 alembic -c new.ini upgrade head
6023
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
153
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
154 If you are performing a *downgrade*: Run the following command to
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
155 downgrade your database to the given version::
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
156
7490
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
157 alembic -c new.ini downgrade 0.4
6023
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
158
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
159 Alembic will show the necessary migrations (if any) as it executes them.
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
160 If no "ERROR" is displayed, the command was successful.
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
161
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
162 Should an error occur, the database may be "stranded" half-way
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
163 through the migration, and you should restore it from backup.
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
164
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
165 Enabling old Kallithea config files for Alembic use
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
166 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
167
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
168 Kallithea configuration files created before the introduction of Alembic
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
169 (i.e. predating Kallithea 0.4) need to be updated for use with Alembic.
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
170 Without this, Alembic will fail with an error like this::
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
171
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
172 FAILED: No config file 'my.ini' found, or file has no '[alembic]' section
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
173
7490
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
174 .. note::
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
175 If you followed this upgrade guide correctly, you will have created a
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
176 new configuration file in section :ref:`Upgrading your configuration
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
177 <upgrade_config>`. When calling Alembic, make
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
178 sure to use this new config file. In this case, you should not get any
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
179 errors and the below manual steps should not be needed.
14e8dcffd279 docs: upgrade: clarify database upgrade instructions
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7437
diff changeset
180
6023
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
181 If Alembic complains specifically about a missing ``alembic.ini``, it is
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
182 likely because you did not specify a config file using the ``-c`` option.
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
183 On the other hand, if the mentioned config file actually exists, you
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
184 need to append the following lines to it::
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
185
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
186 [alembic]
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
187 script_location = kallithea:alembic
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
188
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
189 Your config file should now work with Alembic.
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
190
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
191
7492
a2abde4062ec docs: upgrade: front-end should be built for all installation methods
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7491
diff changeset
192 7. Prepare the front-end
a2abde4062ec docs: upgrade: front-end should be built for all installation methods
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7491
diff changeset
193 ------------------------
a2abde4062ec docs: upgrade: front-end should be built for all installation methods
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7491
diff changeset
194
a2abde4062ec docs: upgrade: front-end should be built for all installation methods
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7491
diff changeset
195 Starting with Kallithea 0.4, external front-end dependencies are no longer
a2abde4062ec docs: upgrade: front-end should be built for all installation methods
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7491
diff changeset
196 shipped but need to be downloaded and/or generated at installation time. Run the
a2abde4062ec docs: upgrade: front-end should be built for all installation methods
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7491
diff changeset
197 following command::
a2abde4062ec docs: upgrade: front-end should be built for all installation methods
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7491
diff changeset
198
a2abde4062ec docs: upgrade: front-end should be built for all installation methods
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7491
diff changeset
199 kallithea-cli front-end-build
a2abde4062ec docs: upgrade: front-end should be built for all installation methods
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7491
diff changeset
200
a2abde4062ec docs: upgrade: front-end should be built for all installation methods
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7491
diff changeset
201
7493
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
202 8. Rebuild the Whoosh full-text index
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
203 -------------------------------------
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
204
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
205 It is recommended that you rebuild the Whoosh index after upgrading since
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
206 new Whoosh versions can introduce incompatible index changes.
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
207
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
208
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
209 9. Start the Kallithea web application
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
210 --------------------------------------
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
211
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
212 This step once again depends entirely on the web server software used to
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
213 serve Kallithea.
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
214
7494
874ed3e58579 docs: upgrade: misc. clarification on upgrade from 0.3.x to 0.4
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7493
diff changeset
215 If you were running Kallithea 0.3.x or older and were using ``paster serve
874ed3e58579 docs: upgrade: misc. clarification on upgrade from 0.3.x to 0.4
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7493
diff changeset
216 my.ini`` before, then the corresponding command in Kallithea 0.4 and later is::
874ed3e58579 docs: upgrade: misc. clarification on upgrade from 0.3.x to 0.4
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7493
diff changeset
217
874ed3e58579 docs: upgrade: misc. clarification on upgrade from 0.3.x to 0.4
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7493
diff changeset
218 gearbox serve -c new.ini
874ed3e58579 docs: upgrade: misc. clarification on upgrade from 0.3.x to 0.4
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7493
diff changeset
219
7493
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
220 Before starting the new version of Kallithea, you may find it helpful to
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
221 clear out your log file so that new errors are readily apparent.
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
222
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
223 .. note::
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
224 If you're using Celery, make sure you restart all instances of it after
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
225 upgrade.
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
226
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
227
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
228 10. Update Git repository hooks
b3644eeee445 docs: upgrade: recreating git hooks can only be done after starting Kallithea
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7492
diff changeset
229 -------------------------------
7378
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
230
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
231 It is possible that an upgrade involves changes to the Git hooks installed by
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
232 Kallithea. As these hooks are created inside the repositories on the server
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
233 filesystem, they are not updated automatically when upgrading Kallithea itself.
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
234
8776
92894fccc615 repo-scan: recommend running this to reinstall Git hooks after upgrading
Mads Kiilerich <mads@kiilerich.com>
parents: 8655
diff changeset
235 To update the hooks of your Git repositories, run::
92894fccc615 repo-scan: recommend running this to reinstall Git hooks after upgrading
Mads Kiilerich <mads@kiilerich.com>
parents: 8655
diff changeset
236
92894fccc615 repo-scan: recommend running this to reinstall Git hooks after upgrading
Mads Kiilerich <mads@kiilerich.com>
parents: 8655
diff changeset
237 kallithea-cli repo-scan -c my.ini --install-git-hooks
92894fccc615 repo-scan: recommend running this to reinstall Git hooks after upgrading
Mads Kiilerich <mads@kiilerich.com>
parents: 8655
diff changeset
238
92894fccc615 repo-scan: recommend running this to reinstall Git hooks after upgrading
Mads Kiilerich <mads@kiilerich.com>
parents: 8655
diff changeset
239 Or:
7378
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
240
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
241 * Go to *Admin > Settings > Remap and Rescan*
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
242 * Select the checkbox *Install Git hooks*
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
243 * Click the button *Rescan repositories*
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
244
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
245 .. note::
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
246 Kallithea does not use hooks on Mercurial repositories. This step is thus
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
247 not necessary if you only have Mercurial repositories.