Files
@ 2c3d30095d5e
Branch filter:
Location: kallithea/docs/upgrade.rst
2c3d30095d5e
5.8 KiB
text/prs.fallenstein.rst
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.
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 | .. _upgrade:
===================
Upgrading Kallithea
===================
This describes the process for upgrading Kallithea, independently of the
Kallithea installation method.
.. note::
If you are upgrading from a RhodeCode installation, you must first
install Kallithea 0.3.2 and follow the instructions in the 0.3.2
README to perform a one-time conversion of the database from
RhodeCode to Kallithea, before upgrading to the latest version
of Kallithea.
1. Stop the Kallithea web application
-------------------------------------
This step depends entirely on the web server software used to serve
Kallithea, but in any case, Kallithea should not be running during
the upgrade.
.. note::
If you're using Celery, make sure you stop all instances during the
upgrade.
2. Create a backup of both database and configuration
-----------------------------------------------------
You are of course strongly recommended to make backups regularly, but it
is *especially* important to make a full database and configuration
backup before performing a Kallithea upgrade.
Back up your configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^
Make a copy of your Kallithea configuration (``.ini``) file.
If you are using :ref:`rcextensions <customization>`, you should also
make a copy of the entire ``rcextensions`` directory.
Back up your database
^^^^^^^^^^^^^^^^^^^^^
If using SQLite, simply make a copy of the Kallithea database (``.db``)
file.
If using PostgreSQL, please consult the documentation for the ``pg_dump``
utility.
If using MySQL, please consult the documentation for the ``mysqldump``
utility.
Look for ``sqlalchemy.url`` in your configuration file to determine
database type, settings, location, etc.
3. Activate the Kallithea virtual environment (if any)
------------------------------------------------------
Verify that you are using the Python environment that you originally
installed Kallithea in by running::
pip freeze
This will list all packages installed in the current environment. If
Kallithea isn't listed, activate the correct virtual environment.
See the appropriate installation page for details.
4. Install new version of Kallithea
-----------------------------------
Please refer to the instructions for the installation method you
originally used to install Kallithea.
If you originally installed using pip, it is as simple as::
pip install --upgrade kallithea
If you originally installed from version control, it is as simple as::
cd my-kallithea-clone
hg pull -u
pip install -e .
5. Upgrade your configuration
-----------------------------
Run the following command to upgrade your configuration (``.ini``) file::
TODO make-config Kallithea my.ini
This will display any changes made by the new version of Kallithea to your
current configuration, and attempt an automatic merge. It is recommended
that you check the contents after the merge.
.. note::
Please always make sure your ``.ini`` files are up to date. Errors
can often be caused by missing parameters added in new versions.
.. _upgrade_db:
6. Upgrade your database
------------------------
.. note::
If you are *downgrading* Kallithea, you should perform the database
migration step *before* installing the older version. (That is,
always perform migrations using the most recent of the two versions
you're migrating between.)
First, run the following command to see your current database version::
alembic -c my.ini current
Typical output will be something like "9358dc3d6828 (head)", which is
the current Alembic database "revision ID". Write down the entire output
for troubleshooting purposes.
The output will be empty if you're upgrading from Kallithea 0.3.x or
older. That's expected. If you get an error that the config file was not
found or has no ``[alembic]`` section, see the next section.
Next, if you are performing an *upgrade*: Run the following command to
upgrade your database to the current Kallithea version::
alembic -c my.ini upgrade head
If you are performing a *downgrade*: Run the following command to
downgrade your database to the given version::
alembic -c my.ini downgrade 0.4
Alembic will show the necessary migrations (if any) as it executes them.
If no "ERROR" is displayed, the command was successful.
Should an error occur, the database may be "stranded" half-way
through the migration, and you should restore it from backup.
Enabling old Kallithea config files for Alembic use
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Kallithea configuration files created before the introduction of Alembic
(i.e. predating Kallithea 0.4) need to be updated for use with Alembic.
Without this, Alembic will fail with an error like this::
FAILED: No config file 'my.ini' found, or file has no '[alembic]' section
If Alembic complains specifically about a missing ``alembic.ini``, it is
likely because you did not specify a config file using the ``-c`` option.
On the other hand, if the mentioned config file actually exists, you
need to append the following lines to it::
[alembic]
script_location = kallithea:alembic
Your config file should now work with Alembic.
7. Rebuild the Whoosh full-text index
-------------------------------------
It is recommended that you rebuild the Whoosh index after upgrading since
new Whoosh versions can introduce incompatible index changes.
8. Start the Kallithea web application
--------------------------------------
This step once again depends entirely on the web server software used to
serve Kallithea.
Before starting the new version of Kallithea, you may find it helpful to
clear out your log file so that new errors are readily apparent.
.. note::
If you're using Celery, make sure you restart all instances of it after
upgrade.
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
|