Since the # is stripped away, `issue_prefix` is prepended to the link text.

`issue_prefix` doesn't necessarily need to be #: if you set issue

prefix to ISSUE- this will generate a URL in format::

  <a href="https://myissueserver.com/example_repo/issue/300">ISSUE-300</a>

If needed, more than one pattern can be specified by appending a unique suffix to

the variables. For example::

    issue_pat_wiki = (?:wiki-)(.+)

    issue_server_link_wiki = https://mywiki.com/{id}

    issue_prefix_wiki = WIKI-

With these settings, wiki pages can be referenced as wiki-some-id, and every

such reference will be transformed into::

  <a href="https://mywiki.com/some-id">WIKI-some-id</a>

Hook management

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

Hooks can be managed in similar way to this used in .hgrc files.

To access hooks setting click `advanced setup` on Hooks section of Mercurial

Settings in Admin.

There are 4 built in hooks that cannot be changed (only enable/disable by

checkboxes on previos section).

To add another custom hook simply fill in first section with

<name>.<hook_type> and the second one with hook path. Example hooks

can be found at *kallithea.lib.hooks*.

Changing default encoding

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

By default, Kallithea uses UTF-8 encoding.

It is configurable as `default_encoding` in the .ini file.

This affects many parts in Kallithea including user names, filenames, and

encoding of commit messages. In addition Kallithea can detect if `chardet`

library is installed. If `chardet` is detected Kallithea will fallback to it

when there are encode/decode errors.

Celery configuration

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

Celery is configured in the Kallithea ini configuration files.

Simply set use_celery=true in the ini file then add / change the configuration

variables inside the ini file.

Remember that the ini files use the format with '.' not with '_' like celery.

So for example setting `BROKER_HOST` in celery means setting `broker.host` in

the config file.

In order to start using celery run::

 paster celeryd <configfile.ini>

.. note::

   Make sure you run this command from the same virtualenv, and with the same

   user that Kallithea runs.

HTTPS support

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

Kallithea will by default generate URLs based on the WSGI environment.

Alternatively, you can use some special configuration settings to control

directly which scheme/protocol Kallithea will use when generating URLs:

- With `https_fixup = true`, the scheme will be taken from the HTTP_X_URL_SCHEME,

  HTTP_X_FORWARDED_SCHEME or HTTP_X_FORWARDED_PROTO HTTP header (default 'http').

- With `force_https = true` the default will be 'https'.

- With `use_htsts = true`, it will set Strict-Transport-Security when using https.

Nginx virtual host example

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

Sample config for nginx using proxy::

    upstream kallithea {

        server 127.0.0.1:5000;

        # add more instances for load balancing

        #server 127.0.0.1:5001;

        #server 127.0.0.1:5002;

    }

    ## gist alias

    server {

       listen          443;

       server_name     gist.myserver.com;

       access_log      /var/log/nginx/gist.access.log;

       error_log       /var/log/nginx/gist.error.log;

       ssl on;

       ssl_certificate     gist.your.kallithea.server.crt;

       ssl_certificate_key gist.your.kallithea.server.key;

       ssl_session_timeout 5m;

       ssl_protocols SSLv3 TLSv1;

       ssl_ciphers DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:EDH-RSA-DES-CBC3-SHA:AES256-SHA:DES-CBC3-SHA:AES128-SHA:RC4-SHA:RC4-MD5;

       ssl_prefer_server_ciphers on;

       rewrite ^/(.+)$ https://your.kallithea.server/_admin/gists/$1;

       rewrite (.*)    https://your.kallithea.server/_admin/gists;

    }

    server {

       listen          443;

       server_name     your.kallithea.server;

       access_log      /var/log/nginx/kallithea.access.log;

       error_log       /var/log/nginx/kallithea.error.log;

       ssl on;

       ssl_certificate     your.kallithea.server.crt;

       ssl_certificate_key your.kallithea.server.key;

       ssl_session_timeout 5m;

       ssl_protocols SSLv3 TLSv1;

       ssl_ciphers DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:EDH-RSA-DES-CBC3-SHA:AES256-SHA:DES-CBC3-SHA:AES128-SHA:RC4-SHA:RC4-MD5;

       ssl_prefer_server_ciphers on;

       ## uncomment root directive if you want to serve static files by nginx

       ## requires static_files = false in .ini file

       #root /path/to/installation/kallithea/public;

       include         /etc/nginx/proxy.conf;

       location / {

            try_files $uri @kallithea;

       }

       location @kallithea {

            proxy_pass      http://kallithea;

       }

    }

Here's the proxy.conf. It's tuned so it will not timeout on long

pushes or large pushes::

    proxy_redirect              off;

    proxy_set_header            Host $host;

    ## needed for container auth

    #proxy_set_header            REMOTE_USER $remote_user;

    #proxy_set_header            X-Forwarded-User $remote_user;

    proxy_set_header            X-Url-Scheme $scheme;

    proxy_set_header            X-Host $http_host;

    proxy_set_header            X-Real-IP $remote_addr;

    proxy_set_header            X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_set_header            Proxy-host $proxy_host;

    proxy_buffering             off;

    proxy_connect_timeout       7200;

    proxy_send_timeout          7200;

    proxy_read_timeout          7200;

    proxy_buffers               8 32k;

    client_max_body_size        1024m;

    client_body_buffer_size     128k;

    large_client_header_buffers 8 64k;

Apache virtual host reverse proxy example

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

Here is a sample configuration file for apache using proxy::

    <VirtualHost *:80>

            ServerName hg.myserver.com

            ServerAlias hg.myserver.com

            <Proxy *>

              Order allow,deny

              Allow from all

            </Proxy>

            #important !

            #Directive to properly generate url (clone url) for pylons

            ProxyPreserveHost On

            #kallithea instance

            ProxyPass / http://127.0.0.1:5000/

            ProxyPassReverse / http://127.0.0.1:5000/

            #to enable https use line below

            #SetEnvIf X-Url-Scheme https HTTPS=1

    </VirtualHost>

Additional tutorial

Apache as subdirectory

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

Apache subdirectory part::

    <Location /<someprefix> >

      ProxyPass http://127.0.0.1:5000/<someprefix>

      ProxyPassReverse http://127.0.0.1:5000/<someprefix>

      SetEnvIf X-Url-Scheme https HTTPS=1

    </Location>

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's WSGI config

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

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::

    aptitude install libapache2-mod-wsgi

- Enable mod_wsgi::

    a2enmod wsgi

- Create a wsgi dispatch script, like the one below. Make sure you

  check the paths correctly point to where you installed Kallithea

  and its Python Virtual Environment.

- Enable the WSGIScriptAlias directive for the wsgi dispatch script,

  as in the following example. Once again, check the paths are

  correctly specified.

Here is a sample excerpt from an Apache Virtual Host configuration file::

    WSGIDaemonProcess kallithea \

        processes=1 threads=4 \

        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::

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

Example wsgi dispatch script::

    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

    site.addsitedir("/srv/kallithea/pyenv/lib/python2.7/site-packages")

    from paste.deploy import loadapp

    from paste.script.util.logging_config import fileConfig

    fileConfig('/srv/kallithea/my.ini')

    application = loadapp('config:/srv/kallithea/my.ini')

Or using proper virtualenv activation::

    activate_this = '/srv/kallithea/venv/bin/activate_this.py'

    execfile(activate_this,dict(__file__=activate_this))

    import os

    os.environ['HOME'] = '/srv/kallithea'

    ini = '/srv/kallithea/kallithea.ini'

    from paste.script.util.logging_config import fileConfig

    fileConfig(ini)

    from paste.deploy import loadapp

    application = loadapp('config:' + ini)

Other configuration files

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

Some example init.d scripts can be found in init.d directory: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/

.. _virtualenv: http://pypi.python.org/pypi/virtualenv

.. _python: http://www.python.org/

.. _Mercurial: http://mercurial.selenic.com/

.. _celery: http://celeryproject.org/

.. _rabbitmq: http://www.rabbitmq.com/

.. _python-ldap: http://www.python-ldap.org/

.. _mercurial-server: http://www.lshift.net/mercurial-server.html

.. _PublishingRepositories: http://mercurial.selenic.com/wiki/PublishingRepositories