================================================================

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

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.

Remember the specific major and minor versions installed, because they will

be needed in the next step. In this case, it is "2.7".

Add Python BIN folder to the path. This can be done manually (editing

"PATH" environment variable) or by using Windows Support Tools that

come pre-installed in Windows Vista/7 and later.

Open a CMD and type::

  SETX PATH "%PATH%;[your-python-path]" /M

Please substitute [your-python-path] with your Python installation

path. Typically this is ``C:\\Python27``.

Download pywin32 from:

http://sourceforge.net/projects/pywin32/files/

- Click on "pywin32" folder

- Click on the first folder (in this case, Build 219, maybe newer when you try)

- Choose the file ending with ".amd64-py2.x.exe" (".win32-py2.x.exe"

  for Win32) where x is the minor version of Python you installed.

  When writing this guide, the file was:

  http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win-amd64-py2.7.exe/download

  (x64)

  http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win32-py2.7.exe/download

  (Win32)

pip is a package management system for Python. You will need it to install Kallithea and its dependencies.

If you installed Python 2.7.9+, you already have it (as long as you ran the installer with admin privileges or disabled UAC).

If it was not installed or if you are using Python>=2.6,<2.7.9:

- Go to https://bootstrap.pypa.io

- Right-click on get-pip.py and choose Saves as...

- Run "python get-pip.py" in the folder where you downloaded get-pip.py (may require admin access).

.. note::

   See http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows

   for details and alternative methods.

Note that pip.exe will be placed inside your Python installation's

Scripts folder, which is likely not on your path. To correct this,

open a CMD and type::

  SETX PATH "%PATH%;[your-python-path]\Scripts" /M

Create a Kallithea folder structure.

This is only an example to install Kallithea. Of course, you can

change it. However, this guide will follow the proposed structure, so

please later adapt the paths if you change them. Folders without

spaces are recommended.

Create the following folder structure::

  C:\Kallithea

  C:\Kallithea\Bin

  C:\Kallithea\Env

  C:\Kallithea\Repos

.. note::

   A python virtual environment will allow for isolation between the Python packages of your system and those used for Kallithea.

   It is strongly recommended to use it to ensure that Kallithea does not change a dependency that other software uses or vice versa.

In a command prompt type::

  pip install virtualenv

Virtualenv will now be inside your Python Scripts path (C:\\Python27\\Scripts or similar).

To create a virtual environment, run::

  virtualenv C:\Kallithea\Env

In order to install Kallithea, you need to be able to run "pip install kallithea". It will use pip to install the Kallithea Python package and its dependencies.

Some Python packages use managed code and need to be compiled.

This can be done on Linux without any special steps. On Windows, you will need to install Microsoft Visual C++ compiler for Python 2.7.

Download and install "Microsoft Visual C++ Compiler for Python 2.7" from http://aka.ms/vcpython27

.. note::

  You can also install the dependencies using already compiled Windows binaries packages. A good source of compiled Python packages is http://www.lfd.uci.edu/~gohlke/pythonlibs/. However, not all of the necessary packages for Kallithea are on this site and some are hard to find, so we will stick with using the compiler.

In a command prompt type (adapting paths if necessary)::

  cd C:\Kallithea\Env\Scripts

  activate

The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar

(depending of your folder structure). Then type::

  pip install kallithea

.. note:: This will take some time. Please wait patiently until it is fully

          complete. Some warnings will appear. Don't worry, they are

          normal.

Mercurial being a python package, it was installed automatically when doing "pip install kallithea".

You need to install git manually if you want Kallithea to be able to host git repositories.

See http://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Windows for instructions.

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

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.

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.

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

Optional: You can also install MinGW, but VS2008 installation is easier.

Download "Visual C++ 2008 Express Edition with SP1" from:

http://download.microsoft.com/download/E/8/E/E8EEB394-7F42-4963-A2D8-29559B738298/VS2008ExpressWithSP1ENUX1504728.iso

(if not found or relocated, google for "visual studio 2008 express" for updated link. This link was taken from http://stackoverflow.com/questions/15318560/visual-c-2008-express-download-link-dead)

You can also download full ISO file for offline installation, just

choose "Visual C++ 2008 Express" when installing.

.. note::

   Using other versions of Visual Studio will lead to random crashes.

   You must use Visual Studio 2008!"

.. note::

   Silverlight Runtime and SQL Server 2008 Express Edition are not

   required, you can uncheck them

Installation methods

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

Kallithea must be installed on a server. Kallithea is installed in a Python

environment so it can use packages that are installed there and make itself

available for other packages.

Two different cases will pretty much cover the options for how it can be

installed.

  can be used in production. The Kallithea maintainers use the development

  branch in production. The advantage of installation from source and regularly

  updating it is that you take advantage of the most recent improvements. Using

  it directly from a DVCS also means that it is easy to track local customizations.

  Running ``setup.py develop`` in the source will use pip to install the

  necessary dependencies in the Python environment and create a

  ``.../site-packages/Kallithea.egg-link`` file there that points at the Kallithea

  source.

- Kallithea can also be installed from ready-made packages using a package manager.

  The official released versions are available on PyPI_ and can be downloaded and

    LDAPS connection

        Enable LDAPS connections. It will likely require `Port`_ to be set to

        a different value (standard LDAPS port is 636). When LDAPS is enabled

        then `Certificate Checks`_ is required.

    START_TLS on LDAP connection

        START TLS connection

.. _Certificate Checks:

Certificate Checks : optional

    `Enable LDAPS`_ is enabled.  Only DEMAND or HARD offer full SSL security

    while the other options are susceptible to man-in-the-middle attacks.  SSL

    certificates can be installed to /etc/openldap/cacerts so that the

    DEMAND or HARD options can be used with self-signed certificates or

    certificates that do not have traceable certificates of authority.

    NEVER

        A serve certificate will never be requested or checked.

    ALLOW

        A server certificate is requested.  Failure to provide a

        certificate or providing a bad certificate will not terminate the

Besides the regular apache setup you will need to add the following line

into ``[app:main]`` section of your .ini file::

    filter-with = proxy-prefix

Add the following at the end of the .ini file::

    [filter:proxy-prefix]

    use = egg:PasteDeploy#prefix

    prefix = /<someprefix>

then change ``<someprefix>`` into your chosen prefix

Apache with mod_wsgi

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

Alternatively, Kallithea can be set up with Apache under mod_wsgi. For

that, you'll need to:

- Install mod_wsgi. If using a Debian-based distro, you can install

  the package libapache2-mod-wsgi::

        python-path=/srv/kallithea/pyenv/lib/python2.7/site-packages

    WSGIScriptAlias / /srv/kallithea/dispatch.wsgi

    WSGIPassAuthorization On

Or if using a dispatcher WSGI script with proper virtualenv activation:

.. code-block:: apache

    WSGIDaemonProcess kallithea processes=1 threads=4

    WSGIScriptAlias / /srv/kallithea/dispatch.wsgi

    WSGIPassAuthorization On

.. note::

   When running apache as root, please make sure it doesn't run Kallithea as

   root, for examply by adding: ``user=www-data group=www-data`` to the configuration.

.. note::

   If running Kallithea in multiprocess mode,

   make sure you set ``instance_id = *`` in the configuration so each process

   gets it's own cache invalidation key.

Example WSGI dispatch script:

.. code-block:: python

    import os

    os.environ["HGENCODING"] = "UTF-8"

    os.environ['PYTHON_EGG_CACHE'] = '/srv/kallithea/.egg-cache'

    # sometimes it's needed to set the curent dir

    os.chdir('/srv/kallithea/')

    import site

{% extends "basic/layout.html" %}

{% block sidebarlogo %}

<div style="text-align:center;margin:30px 0;">

  <img src="{{pathto('_static/kallithea-logo.svg',1)}}" width="200px"/>

</div>

<h3>Support Kallithea development</h3>

<div style="text-align:center">

<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">

<input type="hidden" name="cmd" value="_s-xclick">

<input type="hidden" name="hosted_button_id" value="EYXFS3SQPHYUL">

<img alt="" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">

</form>

    <div style="padding:5px">

     <a href="https://flattr.com/thing/922714/Donate-to-Software-Freedom-Conservancy" target="_blank">

     <img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0" /></a>

    </div>

</div>

{% endblock %}}