Mercurial > kallithea
changeset 4924:7c952ea3d7b3
docs/installation: clarify and reorder alternative installation methods
- Add an introduction describing the different installation methods and their
pros/cons.
- Clarify that Python 3.x is not currently supported.
- Move standard pip install method as last method, and rename as also in
virtualenv we are installing from Python Package Index.
author | Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> |
---|---|
date | Sun, 15 Mar 2015 22:08:54 +0100 |
parents | 422667bdb47b |
children | 56cd202b777e |
files | docs/installation.rst |
diffstat | 1 files changed, 60 insertions(+), 26 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/installation.rst Thu Mar 12 15:34:24 2015 +0100 +++ b/docs/installation.rst Sun Mar 15 22:08:54 2015 +0100 @@ -4,17 +4,39 @@ Installation on Unix/Linux ========================== -**Kallithea** is written entirely in Python. Kallithea requires Python version -2.6 or higher. +**Kallithea** is written entirely in Python and requires Python version +2.6 or higher. Python 3.x is currently not supported. + +There are several ways to install Kallithea: -.. Note:: Alternative very detailed installation instructions for Ubuntu Server - with celery, indexer and daemon scripts: https://gist.github.com/4546398 +- :ref:`installation-source`: The Kallithea development repository is stable + and can be used in production. In fact, the Kallithea maintainers do + use it in production. The advantage of installation from source and regularly + updating it is that you take advantage of the most recent improvements, which + is particularly useful because Kallithea is evolving rapidly. -Installing Kallithea from repository source -------------------------------------------- +- :ref:`installation-virtualenv`: If you prefer to only use released versions + of Kallithea, the recommended method is to install Kallithea in a virtual + Python environment using `virtualenv`. The advantages of this method over + direct installation is that Kallithea and its dependencies are completely + contained inside the virtualenv (which also means you can have multiple + installations side by side or remove it entirely by just removing the + virtualenv directory) and does not require root privileges. -The Kallithea development repository is stable and can be used in production. -Follow these instructions:: +- :ref:`installation-without-virtualenv`: The alternative method of installing + a Kallithea release is using standard pip. The package will be installed in + 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 not are + needed by other packages. + +.. _installation-source: + +Installation from repository source +----------------------------------- + +To install Kallithea from source in a virtualenv, follow the instructions +below:: hg clone https://kallithea-scm.org/repos/kallithea cd kallithea @@ -27,39 +49,32 @@ To upgrade, simply update the repository with ``hg pull -u`` and restart the server. -Installing Kallithea from Python Package Index (PyPI) ------------------------------------------------------ - -**Kallithea** can be installed from PyPI with:: +.. _installation-virtualenv: - pip install kallithea - - -Installation in 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 things will be less problematic when upgrading the -system or Kallithea. +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 - using virtualenv command:: + in for example `/srv/kallithea/venv` using the virtualenv command:: virtualenv /srv/kallithea/venv .. note:: Older versions of virtualenv required ``--no-site-packages`` to work correctly. It should no longer be necessary. -- this will install new virtualenv_ into `/srv/kallithea/venv`. - Activate the virtualenv_ in your current shell session by running:: source /srv/kallithea/venv/bin/activate -.. note:: If you're using UNIX, *do not* use ``sudo`` to run the - ``virtualenv`` script. It's perfectly acceptable (and desirable) - to create a virtualenv as a normal user. +.. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it + will "activate" a shell that terminates immediately. It is also perfectly + acceptable (and desirable) to create a virtualenv as a normal user. - Make a folder for Kallithea data files, and configuration somewhere on the filesystem. For example:: @@ -78,9 +93,28 @@ - This will install Kallithea together with pylons and all other required python libraries into the activated virtualenv. +You can now proceed to :ref:`setup`. -Requirements for Celery (optional) ----------------------------------- +.. _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`. + +Celery (optional) +----------------- In order to gain maximum performance there are some third-party you must install. When Kallithea is used