Mercurial > kallithea

annotate docs/upgrade.rst @ 8309:68bbfd164b23

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
scripts: in regexps, use + when we actually want to make long matches instead of empty Greedyness seems to have changed with Python 3 and it is less forgiving and would happily make empty matches everywhere.
author Mads Kiilerich <mads@kiilerich.com>
date Sat, 28 Mar 2020 15:28:25 +0100
parents 89e9aef9b983
children b688a2a1b189
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
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
42 If you are using :ref:`rcextensions <customization>`, you should also
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
43 make a copy of the entire ``rcextensions`` directory.
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
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
54 If using MySQL, please consult the documentation for the ``mysqldump``
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
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
235 To update the hooks of your Git repositories:
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
236
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
237 * 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
238 * 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
239 * 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
240
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
241 .. note::
415cc651bd83 docs: upgrade: add section on updating git hooks
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7099
diff changeset
242 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
243 not necessary if you only have Mercurial repositories.