Changeset - 8075ec3d0233
Parent rev.
Child rev.
[Not reviewed]
default
0 4 1
Søren Løvborg - 9 years ago 2016-05-23 19:14:48
sorenl@unity3d.com
docs: restructure Kallithea upgrade instructions

This creates a separate "Upgrading Kallithea" section, instead of trying
(and failing) to repeat the same information for each installation page.
Trying to maintain upgrade instructions for each installation method was
perhaps overly ambitious. In practice, only the Linux instructions were
up-to-date.

(Incidentally, this is kind of a throwback to Kallithea 0.1, which also
had a separate upgrade section.)
5 files changed with 152 insertions and 142 deletions:
docs/index.rst
1
docs/installation.rst
88
docs/installation_win.rst
5
29
docs/installation_win_old.rst
6
25
docs/upgrade.rst
140
0 comments (0 inline, 0 general)
docs/index.rst
➞
Show inline comments
 
@@ -20,12 +20,13 @@ Kallithea Documentation
 
   installation
 
   installation_win
 
   installation_win_old
 
   installation_iis
 
   setup
 
   installation_puppet
 
   upgrade
 

			




	
	
	
		
 
**Usage**

			




	
	
	
		
 

			




	
	
	
		
 
.. toctree::

			




	
	
	
		
 
   :maxdepth: 1

			




	
	
	
		
 

			




        

    


    
    

    

        

                

                    docs/installation.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -42,15 +42,12 @@ repository, follow the instructions belo

			




	
	
	
		
 
        pip install --upgrade pip setuptools

			




	
	
	
		
 
        pip install -e .

			




	
	
	
		
 
        python2 setup.py compile_catalog   # for translation of the UI

			




	
	
	
		
 

			




	
	
	
		
 
You can now proceed to :ref:`setup`.

			




	
	
	
		
 

			




	
	
	
		
 
To upgrade, simply update the repository with ``hg pull -u`` and restart the

			




	
	
	
		
 
server.

			




	
	
	
		
 

			




	
	
	
		
 
.. _installation-virtualenv:

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Installing a released version in a virtualenv

			




	
	
	
		
 
---------------------------------------------

			




	
	
	
		
 

			




	
	
		
 
@@ -120,93 +117,8 @@ To install as a regular user in ``~/.loc

			




	
	
	
		
 

			




	
	
	
		
 
    pip install --user kallithea

			




	
	
	
		
 

			




	
	
	
		
 
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/

			




        

    


    
    

    

        

                

                    docs/installation_win.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
	
		
 
.. _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

			




	
	
	
		
 
------------------

			




	
	
	
		
 

			




	
	
	
		
 
Target OS: Windows 7 and newer or Windows Server 2008 R2 and newer

			




	
	
		
 
@@ -175,14 +175,14 @@ __ http://notepad-plus-plus.org/

			




	
	
	
		
 

			




	
	
	
		
 
For the sake of simplicity, run it with the default settings. After your edits (if any) in the previous command prompt, type::

			




	
	
	
		
 

			




	
	
	
		
 
  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 <upgrade>`

			




	
	
	
		
 
             to a newer Kallithea version.

			




	
	
	
		
 

			




	
	
	
		
 
The script will ask you for confirmation about creating a new database, answer yes (y)

			




	
	
	
		
 

			




	
	
	
		
 
The script will ask you for the repository path, answer C:\\Kallithea\\Repos (or similar).

			




	
	
	
		
 

			




	
	
	
		
 
The script will ask you for the admin username and password, answer "admin" + "123456" (or whatever you want)

			




	
	
		
 
@@ -216,30 +216,6 @@ What this guide does not cover:

			




	
	
	
		
 
  - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/

			




	
	
	
		
 
  - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service

			




	
	
	
		
 

			




	
	
	
		
 
- 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 `<upgrade.html>`_.

			




        

    


    
    

    

        

                

                    docs/installation_win_old.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
	
		
 
.. _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

			




	
	
	
		
 
------------------

			




	
	
	
		
 

			




	
	
	
		
 
Target OS: Windows XP SP3 32-bit English (Clean installation)

			




	
	
		
 
@@ -214,14 +214,15 @@ character differences between Unix and W

			




	
	
	
		
 

			




	
	
	
		
 
For the sake of simplicity lets run it with the default settings. After

			




	
	
	
		
 
your edits (if any), in the previous Command Prompt, type::

			




	
	
	
		
 

			




	
	
	
		
 
 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 <upgrade>`

			




	
	
	
		
 
             to a newer Kallithea version.

			




	
	
	
		
 

			




	
	
	
		
 
The script will ask you for confirmation about creating a NEW database,

			




	
	
	
		
 
answer yes (y)

			




	
	
	
		
 
The script will ask you for repository path, answer C:\\Kallithea\\Repos

			




	
	
	
		
 
(or similar)

			




	
	
	
		
 
The script will ask you for admin username and password, answer "admin"

			




	
	
		
 
@@ -257,26 +258,6 @@ What this Guide does not cover:

			




	
	
	
		
 
  - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/

			




	
	
	
		
 
  - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service

			




	
	
	
		
 

			




	
	
	
		
 
- 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

			




        

    


    
    

    

        

                

                    docs/upgrade.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
new file 100644

			




	
	
	
		
 
.. _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 <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.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

			




        

    



    


    



    



      

      





    
    0 comments (0 inline, 0 general)
    





    


  

  







  


    




    








    
        
    
    
        This site is powered by
            Kallithea 0.7.0,
        which is
        © 2010–2025 by various authors & licensed under GPLv3.