kallithea Changeset - 8075ec3d0233

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

docs/installation.rst

docs/installation_win.rst

docs/installation_win_old.rst

docs/upgrade.rst

140

0 comments (0 inline, 0 general)

docs/index.rst

➞

Show inline comments

@@ @@ -2,48 +2,49 @@ @@
 #######################
 Kallithea Documentation
 #######################
 **Readme**
 .. toctree::
    :maxdepth: 1
    readme
 **Installation**
 .. toctree::
    :maxdepth: 1
    overview
    installation
    installation_win
    installation_win_old
    installation_iis
    setup
    installation_puppet
    upgrade
 **Usage**
 .. toctree::
    :maxdepth: 1
    usage/general
    usage/vcs_support
    usage/locking
    usage/statistics
 **Administrator's guide**
 .. toctree::
    :maxdepth: 1
    usage/email
    usage/performance
    usage/backup
    usage/debugging
    usage/troubleshooting
    usage/customization
 **Development**

docs/installation.rst

➞

Show inline comments

@@ @@ -24,51 +24,48 @@ The following describes three different @@
   the same location as all other Python packages you have ever installed. As a
   result, removing it is not as straightforward as with a virtualenv, as you'd
   have to remove its dependencies manually and make sure that they are not
   needed by other packages.
 .. _installation-source:
 Installation from repository source
 -----------------------------------
 To install Kallithea in a virtualenv_ using the stable branch of the development
 repository, follow the instructions below::
         hg clone https://kallithea-scm.org/repos/kallithea -u stable
         cd kallithea
         virtualenv ../kallithea-venv
         source ../kallithea-venv/bin/activate
         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
 ---------------------------------------------
 It is highly recommended to use a separate virtualenv_ for installing Kallithea.
 This way, all libraries required by Kallithea will be installed separately from your
 main Python installation and other applications and things will be less
 problematic when upgrading the system or Kallithea.
 An additional benefit of virtualenv_ is that it doesn't require root privileges.
 - Assuming you have installed virtualenv_, create a new virtual environment
   for example, in `/srv/kallithea/venv`, using the virtualenv command::
     virtualenv /srv/kallithea/venv
 - Activate the virtualenv_ in your current shell session and make sure the
   basic requirements are up-to-date by running::
     source /srv/kallithea/venv/bin/activate
     pip install --upgrade pip setuptools
 .. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it
@@ @@ -102,111 +99,26 @@ An additional benefit of virtualenv_ is @@
   python libraries into the activated virtualenv.
 You can now proceed to :ref:`setup`.
 .. _installation-without-virtualenv:
 Installing a released version without virtualenv
 ------------------------------------------------
 For installation without virtualenv, 'just' use::
     pip install kallithea
 Note that this method requires root privileges and will install packages
 globally without using the system's package manager.
 To install as a regular user in ``~/.local``, you can use::
     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
 Tested on Windows 8.1, Windows Server 2008 R2 and Windows Server 2012
 To install on an older version of Windows, see `<installation_win_old.html>`_
 Step 1 -- Install Python
 ^^^^^^^^^^^^^^^^^^^^^^^^
 Install Python 2.x.y (x = 6 or 7). Latest version is recommended. If you need another version, they can run side by side.
 .. warning:: Python 3.x is not supported.
 - Download Python 2.x.y from http://www.python.org/download/
 - Choose and click on the version
 - Click on "Windows X86-64 Installer" for x64 or "Windows x86 MSI installer" for Win32.
 - Disable UAC or run the installer with admin privileges. If you chose to disable UAC, do not forget to reboot afterwards.
 While writing this guide, the latest version was v2.7.9.
@@ @@ -157,89 +157,65 @@ See http://git-scm.com/book/en/v2/Gettin @@
 Step 9 -- Configuring Kallithea
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Steps taken from `<setup.html>`_
 You have to use the same command prompt as in Step 7, so if you closed
 it, reopen it following the same commands (including the "activate"
 one). When ready, type::
   cd C:\Kallithea\Bin
   paster make-config Kallithea production.ini
 Then you must edit production.ini to fit your needs (IP address, IP
 port, mail settings, database, etc.). `NotePad++`__ or a similar text
 editor is recommended to properly handle the newline character
 differences between Unix and Windows.
 __ 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)
 The script will ask you for admin mail, answer "admin@xxxx.com" (or whatever you want).
 If you make a mistake and the script doesn't end, don't worry: start it again.
 If you decided not to install git, you will get errors about it that you can ignore.
 Step 10 -- Running Kallithea
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In the previous command prompt, being in the C:\\Kallithea\\Bin folder, type::
   paster serve production.ini
 Open your web server, and go to http://127.0.0.1:5000
 It works!! :-)
 Remark:
 If it does not work the first time, Ctrl-C the CMD process and start it again. Don't forget the "http://" in Internet Explorer.
 What this guide does not cover:
 - Installing Celery
 - Running Kallithea as a Windows Service. You can investigate here:
   - http://pypi.python.org/pypi/wsgisvc
   - 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)
 + All Windows Updates until 24-may-2012
 .. note::
    This installation is for 32-bit systems, for 64-bit Windows you might need
    to download proper 64-bit versions of the different packages (Windows Installer, Win32py extensions)
    plus some extra tweaks.
    These extra steps haven been marked as "64-bit".
    Tested on Windows Server 2008 R2 SP1, 9-feb-2013.
    If you run into any 64-bit related problems, please check these pages:
    - http://blog.victorjabur.com/2011/06/05/compiling-python-2-7-modules-on-windows-32-and-64-using-msvc-2008-express/
    - http://bugs.python.org/issue7511
 Step 1 -- Install Visual Studio 2008 Express
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Optional: You can also install MinGW, but VS2008 installation is easier.
@@ @@ -196,87 +196,68 @@ Some warnings will appear, don't worry a @@
 Step 8 -- Configuring Kallithea
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 steps taken from http://packages.python.org/Kallithea/setup.html
 You have to use the same Visual Studio 2008 command prompt as Step7, so
 if you closed it reopen it following the same commands (including the
 "activate" one). When ready, just type::
   cd C:\Kallithea\Bin
   paster make-config Kallithea production.ini
 Then, you must edit production.ini to fit your needs (network address and
 port, mail settings, database, whatever). I recommend using NotePad++
 (free) or similar text editor, as it handles well the EndOfLine
 character differences between Unix and Windows
 (http://notepad-plus-plus.org/)
 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"
 + "123456" (or whatever you want)
 The script will ask you for admin mail, answer "admin@xxxx.com" (or
 whatever you want)
 If you make some mistake and the script does not end, don't worry, start
 it again.
 Step 9 -- Running Kallithea
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In the previous command prompt, being in the C:\\Kallithea\\Bin folder,
 just type::
  paster serve production.ini
 Open yout web server, and go to http://127.0.0.1:5000
 It works!! :-)
 Remark:
 If it does not work first time, just Ctrl-C the CMD process and start it
 again. Don't forget the "http://" in Internet Explorer
 What this Guide does not cover:
 - Installing Celery
 - Running Kallithea as Windows Service. You can investigate here:
   - http://pypi.python.org/pypi/wsgisvc
   - 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.
 . 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.
 . 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.
 . 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.
 . 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 .
 . 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.
 . 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``
 . 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.
 . 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)