annotate docs/upgrade.rst @ 6554:2c3d30095d5e

gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack This is a step towards moving away from the Pylons stack to TurboGears2, but still independent of it. Some notes from the porting - it could perhaps be the missing(?) documentation for migrating from paster to gearbox: Note: 'gearbox' without parameters will crash - specify '-h' to get started testing. Replace paster summary = 'yada yada' with the first line of the docstring of the Command class ... or override get_description. Note: All newlines in the docstring will be collapsed and mangle the long help text. Grouping of commands is not possible. Standard commands (for development) can't be customized under the same name or hidden. (Like for paster, the conceptual model also assumes that the sub-command naming is namespaced so commands from other packages won't conflict.) The usage help is fully automated from the declared options. For all deprecated Commands, replace paster hidden = True with gearbox deprecated = True Note: config_file, takes_config_file, min_args and max_args are not available / relevant. The gearbox parser is customized by overriding get_parser - there is nothing like paster update_parser. Gearbox is using argparse instead of optparse ... but argparse add_argument is mostly backwards compatible with optparse add_option. Instead of overriding command or run as in paster, override take_action in gearbox. The parsed arguments are passed to take_action, not available on the command instance. Paster BadCommand is not available and must be handled manually, terminating with sys.exit(1). There is no standard make-config command in gearbox. Paster appinstall has been replaced by the somewhat different setup_app module in gearbox. There is still no clean way to pass parameters to SetupAppCommand and it relies on websetup and other apparently unnecessary complexity. Instead, implement setup-db from scratch. Minor change by Thomas De Schampheleire: add gearbox logging configuration. Because we use logging.config.fileConfig(.inifile) during gearbox command execution, the logging settings need to be correct and contain a block for gearbox logging itself. Otherwise, errors in command processing are not even visible and the command exits silently.
author Mads Kiilerich <madski@unity3d.com>
date Tue, 25 Oct 2016 21:32:24 +0200
parents f973b866fffc
children 213085032127
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
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
58 database type, settings, location, etc.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
59
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 3. Activate the Kallithea virtual environment (if any)
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
62 ------------------------------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
63
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
64 Verify that you are using the Python environment that you originally
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
65 installed Kallithea in by running::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
66
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
67 pip freeze
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
68
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
69 This will list all packages installed in the current environment. If
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
70 Kallithea isn't listed, activate the correct virtual environment.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
71 See the appropriate installation page for details.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
72
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
73
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
74 4. Install new version of Kallithea
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
75 -----------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
76
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
77 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
78 originally used to install Kallithea.
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 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
81
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
82 pip install --upgrade kallithea
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
83
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
84 If you originally installed from version control, it is as simple as::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
85
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
86 cd my-kallithea-clone
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
87 hg pull -u
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
88 pip install -e .
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 5. Upgrade your configuration
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
92 -----------------------------
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 Run the following command to upgrade your configuration (``.ini``) file::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
95
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6214
diff changeset
96 TODO make-config Kallithea my.ini
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
97
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
98 This will display any changes made by the new version of Kallithea to your
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
99 current configuration, and attempt an automatic merge. It is recommended
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
100 that you check the contents after the merge.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
101
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
102 .. note::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
103 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
104 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
105
6023
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
106 .. _upgrade_db:
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
107
5954
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
108
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
109 6. Upgrade your database
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
6023
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
112 .. note::
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
113 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
114 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
115 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
116 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
117
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
118 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
119
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
120 alembic -c my.ini current
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
121
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
122 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
123 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
124 for troubleshooting purposes.
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
125
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
126 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
127 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
128 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
129
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
130 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
131 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
132
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
133 alembic -c my.ini upgrade head
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
134
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
135 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
136 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
137
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
138 alembic -c my.ini downgrade 0.4
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
139
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
140 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
141 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
142
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
143 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
144 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
145
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
146 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
147 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 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
150 (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
151 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
152
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
153 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
154
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
155 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
156 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
157 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
158 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
159
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
160 [alembic]
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
161 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
162
9fd64dd2617d docs: document how to use Alembic for database migrations
Søren Løvborg <sorenl@unity3d.com>
parents: 6014
diff changeset
163 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
164
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
165
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
166 7. Rebuild the Whoosh full-text index
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
167 -------------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
168
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
169 It is recommended that you rebuild the Whoosh index after upgrading since
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
170 new Whoosh versions can introduce incompatible index changes.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
171
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
172
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
173 8. Start the Kallithea web application
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
174 --------------------------------------
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
175
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
176 This step once again depends entirely on the web server software used to
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
177 serve Kallithea.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
178
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
179 Before starting the new version of Kallithea, you may find it helpful to
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
180 clear out your log file so that new errors are readily apparent.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
181
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
182 .. note::
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
183 If you're using Celery, make sure you restart all instances of it after
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
184 upgrade.
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
185
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
186
8075ec3d0233 docs: restructure Kallithea upgrade instructions
Søren Løvborg <sorenl@unity3d.com>
parents:
diff changeset
187 .. _virtualenv: http://pypi.python.org/pypi/virtualenv