diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -23,6 +23,7 @@ Kallithea Documentation installation_iis setup installation_puppet + upgrade **Usage** diff --git a/docs/installation.rst b/docs/installation.rst --- a/docs/installation.rst +++ b/docs/installation.rst @@ -45,9 +45,6 @@ repository, follow the instructions belo You can now proceed to :ref:`setup`. -To upgrade, simply update the repository with ``hg pull -u`` and restart the -server. - .. _installation-virtualenv: @@ -123,90 +120,5 @@ To install as a regular user in ``~/.loc You can now proceed to :ref:`setup`. -Upgrading Kallithea from Python Package Index (PyPI) ----------------------------------------------------- - -.. note:: - It is strongly recommended that you **always** perform a database and - configuration backup before doing an upgrade. - - These directions will use '{version}' to note that this is the version of - Kallithea that these files were used with. If backing up your Kallithea - instance from version 0.1 to 0.2, the ``my.ini`` file could be - backed up to ``my.ini.0-1``. - -If using a SQLite database, stop the Kallithea process/daemon/service, and -then make a copy of the database file:: - - service kallithea stop - cp kallithea.db kallithea.db.{version} - -Back up your configuration file:: - - cp my.ini my.ini.{version} - -Ensure that you are using the Python virtual 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:: - - source /srv/kallithea/venv/bin/activate - -Once you have verified the environment you can upgrade Kallithea with:: - - pip install --upgrade kallithea - -Then run the following command from the installation directory:: - - paster make-config Kallithea my.ini - -This will display any changes made by the new version of Kallithea to your -current configuration. It will try to perform an automerge. It is recommended -that you recheck the content after the automerge. - -.. note:: - Please always make sure your .ini files are up to date. Errors can - often be caused by missing parameters added in new versions. - -It is also recommended that you rebuild the whoosh index after upgrading since -the new whoosh version could introduce some incompatible index changes. Please -read the changelog to see if there were any changes to whoosh. - -The final step is to upgrade the database. To do this simply run:: - - paster upgrade-db my.ini - -This will upgrade the schema and update some of the defaults in the database, -and will always recheck the settings of the application, if there are no new -options that need to be set. - -.. note:: - The DB schema upgrade library has some limitations and can sometimes fail if you try to - upgrade from older major releases. In such a case simply run upgrades sequentially, e.g., - upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X - You can always specify what version of Kallithea you want to install for example in pip - `pip install Kallithea==0.2` - -You may find it helpful to clear out your log file so that new errors are -readily apparent:: - - echo > kallithea.log - -Once that is complete, you may now start your upgraded Kallithea Instance:: - - service kallithea start - -Or:: - - paster serve /srv/kallithea/my.ini - -.. note:: - If you're using Celery, make sure you restart all instances of it after - upgrade. - - .. _virtualenv: http://pypi.python.org/pypi/virtualenv .. _pylons: http://www.pylonsproject.org/ diff --git a/docs/installation_win.rst b/docs/installation_win.rst --- a/docs/installation_win.rst +++ b/docs/installation_win.rst @@ -1,8 +1,8 @@ .. _installation_win: -================================================================ -Installation and upgrade on Windows (7/Server 2008 R2 and newer) -================================================================ +==================================================== +Installation on Windows (7/Server 2008 R2 and newer) +==================================================== First time install @@ -178,8 +178,8 @@ For the sake of simplicity, run it with paster setup-db production.ini .. warning:: This time a *new* database will be installed. You must - follow a different step to later *upgrade* to a newer - Kallithea version) + follow a different process to later :ref:`upgrade ` + to a newer Kallithea version. The script will ask you for confirmation about creating a new database, answer yes (y) @@ -219,27 +219,3 @@ What this guide does not cover: - Using Apache. You can investigate here: - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4 - - -Upgrading ---------- - -Stop running Kallithea -Open a CommandPrompt like in Step 7 (cd to C:\Kallithea\Env\Scripts and activate) and type:: - - pip install kallithea --upgrade - cd \Kallithea\Bin - -Backup your production.ini file now. - -Then run:: - - paster make-config Kallithea production.ini - -Look for changes and update your production.ini accordingly. - -Next, update the database:: - - paster upgrade-db production.ini - -More details can be found in ``_. diff --git a/docs/installation_win_old.rst b/docs/installation_win_old.rst --- a/docs/installation_win_old.rst +++ b/docs/installation_win_old.rst @@ -1,8 +1,8 @@ .. _installation_win_old: -====================================================================== -Installation and upgrade on Windows (XP/Vista/Server 2003/Server 2008) -====================================================================== +========================================================== +Installation on Windows (XP/Vista/Server 2003/Server 2008) +========================================================== First-time install @@ -217,8 +217,9 @@ your edits (if any), in the previous Com paster setup-db production.ini -(this time a NEW database will be installed, you must follow a different -step to later UPGRADE to a newer Kallithea version) +.. warning:: This time a *new* database will be installed. You must + follow a different process to later :ref:`upgrade ` + to a newer Kallithea version. The script will ask you for confirmation about creating a NEW database, answer yes (y) @@ -260,23 +261,3 @@ What this Guide does not cover: - Using Apache. You can investigate here: - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4 - - -Upgrading ---------- - -Stop running Kallithea -Open a CommandPrompt like in Step7 (VS2008 path + activate) and type:: - - easy_install -U kallithea - cd \Kallithea\Bin - -{ backup your production.ini file now} :: - - paster make-config Kallithea production.ini - -(check changes and update your production.ini accordingly) :: - - paster upgrade-db production.ini (update database) - -Full steps in http://packages.python.org/Kallithea/upgrade.html diff --git a/docs/upgrade.rst b/docs/upgrade.rst new file mode 100644 --- /dev/null +++ b/docs/upgrade.rst @@ -0,0 +1,140 @@ +.. _upgrade: + +=================== +Upgrading Kallithea +=================== + +This describes the process for upgrading Kallithea, independently of the +Kallithea installation method. + + +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 `, 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.db1.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:: + + paster 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. + + +6. Upgrade your database +------------------------ + +To do this simply run:: + + paster upgrade-db my.ini + +This will upgrade the schema and update some of the defaults in the database, +and will always recheck the settings of the application, if there are no new +options that need to be set. + +.. note:: + The DB schema upgrade library has some limitations and can sometimes fail if you try to + upgrade from older major releases. In such a case simply run upgrades sequentially, e.g., + upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X. + You can always specify what version of Kallithea you want to install e.g. using pip: + ``pip install Kallithea==0.2`` + + +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