Changeset - ff8651b2f14f
[Not reviewed]
default
0 3 0
Mads Kiilerich (mads) - 6 years ago 2020-06-19 18:24:38
mads@kiilerich.com
Grafted from: d3f2108667ba
docs: augment setup description with more details of http server and database

Dive into more details than in overview.rst .

Databases should perhaps have more mentioning in overview.rst , but there is
nothing but details and thus not much to say in the overview ...
3 files changed with 49 insertions and 21 deletions:
0 comments (0 inline, 0 general)
development.ini
Show inline comments
 
@@ -171,350 +171,350 @@ hgencoding = utf-8
 

	
 
## regular expression to match issue references
 
## This pattern may/should contain parenthesized groups, that can
 
## be referred to in issue_server_link or issue_sub using Python backreferences
 
## (e.g. \1, \2, ...). You can also create named groups with '(?P<groupname>)'.
 
## To require mandatory whitespace before the issue pattern, use:
 
## (?:^|(?<=\s)) before the actual pattern, and for mandatory whitespace
 
## behind the issue pattern, use (?:$|(?=\s)) after the actual pattern.
 

	
 
issue_pat = #(\d+)
 

	
 
## server url to the issue
 
## This pattern may/should contain backreferences to parenthesized groups in issue_pat.
 
## A backreference can be \1, \2, ... or \g<groupname> if you specified a named group
 
## called 'groupname' in issue_pat.
 
## The special token {repo} is replaced with the full repository name
 
## including repository groups, while {repo_name} is replaced with just
 
## the name of the repository.
 

	
 
issue_server_link = https://issues.example.com/{repo}/issue/\1
 

	
 
## substitution pattern to use as the link text
 
## If issue_sub is empty, the text matched by issue_pat is retained verbatim
 
## for the link text. Otherwise, the link text is that of issue_sub, with any
 
## backreferences to groups in issue_pat replaced.
 

	
 
issue_sub =
 

	
 
## issue_pat, issue_server_link and issue_sub can have suffixes to specify
 
## multiple patterns, to other issues server, wiki or others
 
## below an example how to create a wiki pattern
 
## wiki-some-id -> https://wiki.example.com/some-id
 

	
 
#issue_pat_wiki = wiki-(\S+)
 
#issue_server_link_wiki = https://wiki.example.com/\1
 
#issue_sub_wiki = WIKI-\1
 

	
 
## alternative return HTTP header for failed authentication. Default HTTP
 
## response is 401 HTTPUnauthorized. Currently Mercurial clients have trouble with
 
## handling that. Set this variable to 403 to return HTTPForbidden
 
auth_ret_code =
 

	
 
## allows to change the repository location in settings page
 
allow_repo_location_change = True
 

	
 
## allows to setup custom hooks in settings page
 
allow_custom_hooks_settings = True
 

	
 
## extra extensions for indexing, space separated and without the leading '.'.
 
#index.extensions =
 
#    gemfile
 
#    lock
 

	
 
## extra filenames for indexing, space separated
 
#index.filenames =
 
#    .dockerignore
 
#    .editorconfig
 
#    INSTALL
 
#    CHANGELOG
 

	
 
####################################
 
##            SSH CONFIG          ##
 
####################################
 

	
 
## SSH is disabled by default, until an Administrator decides to enable it.
 
ssh_enabled = false
 

	
 
## File where users' SSH keys will be stored *if* ssh_enabled is true.
 
#ssh_authorized_keys = /home/kallithea/.ssh/authorized_keys
 

	
 
## Path to be used in ssh_authorized_keys file to invoke kallithea-cli with ssh-serve.
 
#kallithea_cli_path = /srv/kallithea/venv/bin/kallithea-cli
 

	
 
## Locale to be used in the ssh-serve command.
 
## This is needed because an SSH client may try to use its own locale
 
## settings, which may not be available on the server.
 
## See `locale -a` for valid values on this system.
 
#ssh_locale = C.UTF-8
 

	
 
####################################
 
##         CELERY CONFIG          ##
 
####################################
 

	
 
## Note: Celery doesn't support Windows.
 
use_celery = false
 

	
 
## Celery config settings from https://docs.celeryproject.org/en/4.4.0/userguide/configuration.html prefixed with 'celery.'.
 

	
 
## Example: use the message queue on the local virtual host 'kallitheavhost' as the RabbitMQ user 'kallithea':
 
celery.broker_url = amqp://kallithea:thepassword@localhost:5672/kallitheavhost
 

	
 
celery.result.backend = db+sqlite:///celery-results.db
 

	
 
#celery.amqp.task.result.expires = 18000
 

	
 
celery.worker_concurrency = 2
 
celery.worker_max_tasks_per_child = 1
 

	
 
## If true, tasks will never be sent to the queue, but executed locally instead.
 
celery.task_always_eager = false
 

	
 
####################################
 
##          BEAKER CACHE          ##
 
####################################
 

	
 
beaker.cache.data_dir = %(here)s/data/cache/data
 
beaker.cache.lock_dir = %(here)s/data/cache/lock
 

	
 
beaker.cache.regions = long_term,long_term_file
 

	
 
beaker.cache.long_term.type = memory
 
beaker.cache.long_term.expire = 36000
 
beaker.cache.long_term.key_length = 256
 

	
 
beaker.cache.long_term_file.type = file
 
beaker.cache.long_term_file.expire = 604800
 
beaker.cache.long_term_file.key_length = 256
 

	
 
####################################
 
##        BEAKER SESSION          ##
 
####################################
 

	
 
## Name of session cookie. Should be unique for a given host and path, even when running
 
## on different ports. Otherwise, cookie sessions will be shared and messed up.
 
session.key = kallithea
 
## Sessions should always only be accessible by the browser, not directly by JavaScript.
 
session.httponly = true
 
## Session lifetime. 2592000 seconds is 30 days.
 
session.timeout = 2592000
 

	
 
## Server secret used with HMAC to ensure integrity of cookies.
 
#session.secret = VERY-SECRET
 
session.secret = development-not-secret
 
## Further, encrypt the data with AES.
 
#session.encrypt_key = <key_for_encryption>
 
#session.validate_key = <validation_key>
 

	
 
## Type of storage used for the session, current types are
 
## dbm, file, memcached, database, and memory.
 

	
 
## File system storage of session data. (default)
 
#session.type = file
 

	
 
## Cookie only, store all session data inside the cookie. Requires secure secrets.
 
#session.type = cookie
 

	
 
## Database storage of session data.
 
#session.type = ext:database
 
#session.sa.url = postgresql://postgres:qwe@localhost/kallithea
 
#session.table_name = db_session
 

	
 
####################################
 
##        ERROR HANDLING          ##
 
####################################
 

	
 
## Show a nice error page for application HTTP errors and exceptions (default true)
 
#errorpage.enabled = true
 

	
 
## Enable Backlash client-side interactive debugger (default false)
 
## WARNING: *THIS MUST BE false IN PRODUCTION ENVIRONMENTS!!!*
 
## This debug mode will allow all visitors to execute malicious code.
 
#debug = false
 
debug = true
 

	
 
## Enable Backlash server-side error reporting (unless debug mode handles it client-side) (default true)
 
#trace_errors.enable = true
 
## Errors will be reported by mail if trace_errors.error_email is set.
 

	
 
## Propagate email settings to ErrorReporter of TurboGears2
 
## You do not normally need to change these lines
 
get trace_errors.smtp_server = smtp_server
 
get trace_errors.smtp_port = smtp_port
 
get trace_errors.from_address = error_email_from
 
get trace_errors.error_email = email_to
 
get trace_errors.smtp_username = smtp_username
 
get trace_errors.smtp_password = smtp_password
 
get trace_errors.smtp_use_tls = smtp_use_tls
 

	
 

	
 
##################################
 
##        LOGVIEW CONFIG        ##
 
##################################
 

	
 
logview.sqlalchemy = #faa
 
logview.pylons.templating = #bfb
 
logview.pylons.util = #eee
 

	
 
#########################
 
##      DB CONFIG      ##
 
#########################
 

	
 
sqlalchemy.url = sqlite:///%(here)s/kallithea.db?timeout=60
 
#sqlalchemy.url = postgresql://user:pass@localhost/kallithea
 
#sqlalchemy.url = mysql://user:pass@localhost/kallithea?charset=utf8
 
#sqlalchemy.url = postgresql://kallithea:password@localhost/kallithea
 
#sqlalchemy.url = mysql://kallithea:password@localhost/kallithea?charset=utf8
 
## Note: the mysql:// prefix should also be used for MariaDB
 

	
 
sqlalchemy.pool_recycle = 3600
 

	
 
################################
 
##   ALEMBIC CONFIGURATION    ##
 
################################
 

	
 
[alembic]
 
script_location = kallithea:alembic
 

	
 
################################
 
##   LOGGING CONFIGURATION    ##
 
################################
 

	
 
[loggers]
 
keys = root, routes, kallithea, sqlalchemy, tg, gearbox, beaker, templates, whoosh_indexer, werkzeug, backlash
 

	
 
[handlers]
 
keys = console, console_color, console_color_sql, null
 

	
 
[formatters]
 
keys = generic, color_formatter, color_formatter_sql
 

	
 
#############
 
## LOGGERS ##
 
#############
 

	
 
[logger_root]
 
level = NOTSET
 
#handlers = console
 
## For coloring based on log level:
 
handlers = console_color
 

	
 
[logger_routes]
 
#level = WARN
 
level = DEBUG
 
handlers =
 
qualname = routes.middleware
 
## "level = DEBUG" logs the route matched and routing variables.
 

	
 
[logger_beaker]
 
#level = WARN
 
level = DEBUG
 
handlers =
 
qualname = beaker.container
 

	
 
[logger_templates]
 
#level = WARN
 
level = INFO
 
handlers =
 
qualname = pylons.templating
 

	
 
[logger_kallithea]
 
#level = WARN
 
level = DEBUG
 
handlers =
 
qualname = kallithea
 

	
 
[logger_tg]
 
#level = WARN
 
level = DEBUG
 
handlers =
 
qualname = tg
 

	
 
[logger_gearbox]
 
#level = WARN
 
level = DEBUG
 
handlers =
 
qualname = gearbox
 

	
 
[logger_sqlalchemy]
 
level = WARN
 
handlers =
 
qualname = sqlalchemy.engine
 
## For coloring based on log level and pretty printing of SQL:
 
#level = INFO
 
#handlers = console_color_sql
 
#propagate = 0
 

	
 
[logger_whoosh_indexer]
 
#level = WARN
 
level = DEBUG
 
handlers =
 
qualname = whoosh_indexer
 

	
 
[logger_werkzeug]
 
level = WARN
 
handlers =
 
qualname = werkzeug
 

	
 
[logger_backlash]
 
level = WARN
 
handlers =
 
qualname = backlash
 

	
 
##############
 
## HANDLERS ##
 
##############
 

	
 
[handler_console]
 
class = StreamHandler
 
args = (sys.stderr,)
 
formatter = generic
 

	
 
[handler_console_color]
 
## ANSI color coding based on log level
 
class = StreamHandler
 
args = (sys.stderr,)
 
formatter = color_formatter
 

	
 
[handler_console_color_sql]
 
## ANSI color coding and pretty printing of SQL statements
 
class = StreamHandler
 
args = (sys.stderr,)
 
formatter = color_formatter_sql
 

	
 
[handler_null]
 
class = NullHandler
 
args = ()
 

	
 
################
 
## FORMATTERS ##
 
################
 

	
 
[formatter_generic]
 
format = %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s
 
datefmt = %Y-%m-%d %H:%M:%S
 

	
 
[formatter_color_formatter]
 
class = kallithea.lib.colored_formatter.ColorFormatter
 
format = %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s
 
datefmt = %Y-%m-%d %H:%M:%S
 

	
 
[formatter_color_formatter_sql]
 
class = kallithea.lib.colored_formatter.ColorFormatterSql
 
format = %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s
 
datefmt = %Y-%m-%d %H:%M:%S
 

	
 
#################
 
## SSH LOGGING ##
 
#################
 

	
 
## The default loggers use 'handler_console' that uses StreamHandler with
 
## destination 'sys.stderr'. In the context of the SSH server process, these log
 
## messages would be sent to the client, which is normally not what you want.
 
## By default, when running ssh-serve, just use NullHandler and disable logging
 
## completely. For other logging options, see:
 
## https://docs.python.org/2/library/logging.handlers.html
 

	
 
[ssh_serve:logger_root]
 
level = CRITICAL
 
handlers = null
 

	
 
## Note: If logging is configured with other handlers, they might need similar
 
## muting for ssh-serve too.
docs/setup.rst
Show inline comments
 
.. _setup:
 

	
 
=====
 
Setup
 
=====
 

	
 

	
 
Setting up Kallithea
 
--------------------
 

	
 
Some further details to the steps mentioned in the overview.
 

	
 
Create low level configuration file
 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

	
 
First, you will need to create a Kallithea configuration file. Run the
 
following command to do so::
 
First, you will need to create a Kallithea configuration file. The
 
configuration file is a ``.ini`` file that contains various low level settings
 
for Kallithea, e.g. configuration of how to use database, web server, email,
 
and logging.
 

	
 
    kallithea-cli config-create my.ini
 
Run the following command to create the file ``my.ini`` in the current
 
directory::
 

	
 
This will create the file ``my.ini`` in the current directory. This
 
configuration file contains the various settings for Kallithea, e.g.
 
proxy port, email settings, usage of static files, cache, Celery
 
settings, and logging. Extra settings can be specified like::
 
    kallithea-cli config-create my.ini http_server=waitress
 

	
 
To get a good starting point for your configuration, specify the http server
 
you intend to use. It can be ``waitress``, ``gearbox``, ``gevent``,
 
``gunicorn``, or ``uwsgi``. (Apache ``mod_wsgi`` will not use this
 
configuration file, and it is fine to keep the default http_server configuration
 
unused. ``mod_wsgi`` is configured using ``httpd.conf`` directives and a WSGI
 
wrapper script.)
 

	
 
Extra custom settings can be specified like::
 

	
 
    kallithea-cli config-create my.ini host=8.8.8.8 "[handler_console]" formatter=color_formatter
 

	
 
Populate the database
 
^^^^^^^^^^^^^^^^^^^^^
 

	
 
Next, you need to create the databases used by Kallithea. It is recommended to
 
use PostgreSQL or SQLite (default). If you choose a database other than the
 
default, ensure you properly adjust the database URL in your ``my.ini``
 
configuration file to use this other database. Kallithea currently supports
 
PostgreSQL, SQLite and MariaDB/MySQL databases. Create the database by running
 
the following command::
 
Next, you need to create the databases used by Kallithea. Kallithea currently
 
supports PostgreSQL, SQLite and MariaDB/MySQL databases. It is recommended to
 
start out using SQLite (the default) and move to PostgreSQL if it becomes a
 
bottleneck or to get a "proper" database. MariaDB/MySQL is also supported.
 

	
 
For PostgreSQL, run ``pip install psycopg2`` to get the database driver. Make
 
sure the PostgreSQL server is initialized and running. Make sure you have a
 
database user with password authentication with permissions to create databases
 
- for example by running::
 

	
 
    sudo -u postgres createuser 'kallithea' --pwprompt --createdb
 

	
 
For MariaDB/MySQL, run ``pip install mysqlclient`` to get the ``MySQLdb``
 
database driver. Make sure the database server is initialized and running. Make
 
sure you have a database user with password authentication with permissions to
 
create the database - for example by running::
 

	
 
    echo 'CREATE USER "kallithea"@"localhost" IDENTIFIED BY "password"' | sudo -u mysql mysql
 
    echo 'GRANT ALL PRIVILEGES ON `kallithea`.* TO "kallithea"@"localhost"' | sudo -u mysql mysql
 

	
 
Check and adjust ``sqlalchemy.url`` in your ``my.ini`` configuration file to use
 
this database.
 

	
 
Create the database, tables, and initial content by running the following
 
command::
 

	
 
    kallithea-cli db-create -c my.ini
 

	
 
This will first prompt you for a "root" path. This "root" path is the location
 
where Kallithea will store all of its repositories on the current machine. This
 
location must be writable for the running Kallithea application. Next,
 
``db-create`` will prompt you for a username and password for the initial admin
 
account it sets up for you.
 

	
 
The ``db-create`` values can also be given on the command line.
 
Example::
 

	
 
    kallithea-cli db-create -c my.ini --user=nn --password=secret --email=nn@example.com --repos=/srv/repos
 

	
 
The ``db-create`` command will create all needed tables and an
 
admin account. When choosing a root path you can either use a new
 
empty location, or a location which already contains existing
 
repositories. If you choose a location which contains existing
 
repositories Kallithea will add all of the repositories at the chosen
 
location to its database.  (Note: make sure you specify the correct
 
path to the root).
 

	
 

	
 
Prepare front-end files
 
^^^^^^^^^^^^^^^^^^^^^^^
 

	
 
Finally, the front-end files must be prepared. This requires ``npm`` version 6
 
or later, which needs ``node.js`` (version 12 or later). Prepare the front-end
 
by running::
 

	
 
    kallithea-cli front-end-build
 

	
 
Running
 
^^^^^^^
 

	
 
You are now ready to use Kallithea. To run it simply execute::
 
You are now ready to use Kallithea. To run it using a gearbox web server,
 
simply execute::
 

	
 
    gearbox serve -c my.ini
 

	
 
- This command runs the Kallithea server. The web app should be available at
 
  http://127.0.0.1:5000. The IP address and port is configurable via the
 
  configuration file created in the previous step.
 
- Log in to Kallithea using the admin account created when running ``db-create``.
 
- The default permissions on each repository is read, and the owner is admin.
 
  Remember to update these if needed.
 
- In the admin panel you can toggle LDAP, anonymous, and permissions
 
  settings, as well as edit more advanced options on users and
 
  repositories.
 

	
 

	
 
Internationalization (i18n support)
 
-----------------------------------
 

	
 
The Kallithea web interface is automatically displayed in the user's preferred
 
language, as indicated by the browser. Thus, different users may see the
 
application in different languages. If the requested language is not available
 
(because the translation file for that language does not yet exist or is
 
incomplete), English is used.
 

	
 
If you want to disable automatic language detection and instead configure a
 
fixed language regardless of user preference, set ``i18n.enabled = false`` and
 
specify another language by setting ``i18n.lang`` in the Kallithea
 
configuration file.
 

	
 

	
 
Using Kallithea with SSH
 
------------------------
 

	
 
Kallithea supports repository access via SSH key based authentication.
 
This means:
 

	
 
- repository URLs like ``ssh://kallithea@example.com/name/of/repository``
 

	
 
- all network traffic for both read and write happens over the SSH protocol on
 
  port 22, without using HTTP/HTTPS nor the Kallithea WSGI application
 

	
 
- encryption and authentication protocols are managed by the system's ``sshd``
 
  process, with all users using the same Kallithea system user (e.g.
 
  ``kallithea``) when connecting to the SSH server, but with users' public keys
 
  in the Kallithea system user's `.ssh/authorized_keys` file granting each user
 
  sandboxed access to the repositories.
 

	
 
- users and admins can manage SSH public keys in the web UI
 

	
 
- in their SSH client configuration, users can configure how the client should
 
  control access to their SSH key - without passphrase, with passphrase, and
 
  optionally with passphrase caching in the local shell session (``ssh-agent``).
 
  This is standard SSH functionality, not something Kallithea provides or
 
  interferes with.
 

	
 
- network communication between client and server happens in a bidirectional
 
  stateful stream, and will in some cases be faster than HTTP/HTTPS with several
 
  stateless round-trips.
 

	
 
.. note:: At this moment, repository access via SSH has been tested on Unix
 
    only. Windows users that care about SSH are invited to test it and report
 
    problems, ideally contributing patches that solve these problems.
 

	
 
Users and admins can upload SSH public keys (e.g. ``.ssh/id_rsa.pub``) through
 
the web interface. The server's ``.ssh/authorized_keys`` file is automatically
 
maintained with an entry for each SSH key. Each entry will tell ``sshd`` to run
 
``kallithea-cli`` with the ``ssh-serve`` sub-command and the right Kallithea user ID
 
when encountering the corresponding SSH key.
 

	
 
To enable SSH repository access, Kallithea must be configured with the path to
 
the ``.ssh/authorized_keys`` file for the Kallithea user, and the path to the
 
``kallithea-cli`` command. Put something like this in the ``.ini`` file::
 

	
 
    ssh_enabled = true
 
    ssh_authorized_keys = /home/kallithea/.ssh/authorized_keys
 
    kallithea_cli_path = /srv/kallithea/venv/bin/kallithea-cli
 

	
 
The SSH service must be running, and the Kallithea user account must be active
 
(not necessarily with password access, but public key access must be enabled),
 
all file permissions must be set as sshd wants it, and ``authorized_keys`` must
 
be writeable by the Kallithea user.
 

	
 
.. note:: The ``authorized_keys`` file will be rewritten from scratch on
 
    each update. If it already exists with other data, Kallithea will not
 
    overwrite the existing ``authorized_keys``, and the server process will
 
    instead throw an exception. The system administrator thus cannot ssh
 
    directly to the Kallithea user but must use su/sudo from another account.
 

	
 
    If ``/home/kallithea/.ssh/`` (the directory of the path specified in the
 
    ``ssh_authorized_keys`` setting of the ``.ini`` file) does not exist as a
 
    directory, Kallithea will attempt to create it. If that path exists but is
 
    *not* a directory, or is not readable-writable-executable by the server
 
    process, the server process will raise an exception each time it attempts to
 
    write the ``authorized_keys`` file.
 

	
 
.. note:: It is possible to configure the SSH server to look for authorized
 
   keys in multiple files, for example reserving ``ssh/authorized_keys`` to be
 
   used for normal SSH and with Kallithea using
 
   ``.ssh/authorized_keys_kallithea``. In ``/etc/ssh/sshd_config`` set
 
   ``AuthorizedKeysFile .ssh/authorized_keys .ssh/authorized_keys_kallithea``
 
   and restart sshd, and in ``my.ini`` set ``ssh_authorized_keys =
 
   /home/kallithea/.ssh/authorized_keys_kallithea``. Note that this new
 
   location will apply to all system users, and that multiple entries for the
 
   same SSH key will shadow each other.
 

	
 
.. warning:: The handling of SSH access is steered directly by the command
 
    specified in the ``authorized_keys`` file. There is no interaction with the
 
    web UI.  Once SSH access is correctly configured and enabled, it will work
 
    regardless of whether the Kallithea web process is actually running. Hence,
 
    if you want to perform repository or server maintenance and want to fully
 
    disable all access to the repositories, disable SSH access by setting
 
    ``ssh_enabled = false`` in the correct ``.ini`` file (i.e. the ``.ini`` file
 
    specified in the ``authorized_keys`` file.)
 

	
 
The ``authorized_keys`` file can be updated manually with ``kallithea-cli
 
ssh-update-authorized-keys -c my.ini``. This command is not needed in normal
 
operation but is for example useful after changing SSH-related settings in the
 
``.ini`` file or renaming that file. (The path to the ``.ini`` file is used in
 
the generated ``authorized_keys`` file).
 

	
 

	
 
Setting up Whoosh full text search
 
----------------------------------
 

	
 
Kallithea provides full text search of repositories using `Whoosh`__.
 

	
 
.. __: https://whoosh.readthedocs.io/en/latest/
 

	
 
For an incremental index build, run::
 

	
 
    kallithea-cli index-create -c my.ini
 

	
 
For a full index rebuild, run::
 

	
 
    kallithea-cli index-create -c my.ini --full
 

	
 
The ``--repo-location`` option allows the location of the repositories to be overridden;
 
usually, the location is retrieved from the Kallithea database.
 

	
 
The ``--index-only`` option can be used to limit the indexed repositories to a comma-separated list::
 

	
 
    kallithea-cli index-create -c my.ini --index-only=vcs,kallithea
 

	
 
To keep your index up-to-date it is necessary to do periodic index builds;
 
for this, it is recommended to use a crontab entry. Example::
 

	
 
    0  3  *  *  *  /path/to/virtualenv/bin/kallithea-cli index-create -c /path/to/kallithea/my.ini
 

	
 
When using incremental mode (the default), Whoosh will check the last
 
modification date of each file and add it to be reindexed if a newer file is
 
available. The indexing daemon checks for any removed files and removes them
 
from index.
 

	
 
If you want to rebuild the index from scratch, you can use the ``-f`` flag as above,
 
or in the admin panel you can check the "build from scratch" checkbox.
 

	
 

	
 
Integration with issue trackers
 
-------------------------------
 

	
 
Kallithea provides a simple integration with issue trackers. It's possible
 
to define a regular expression that will match an issue ID in commit messages,
 
and have that replaced with a URL to the issue.
 

	
 
This is achieved with following three variables in the ini file::
 

	
 
    issue_pat = #(\d+)
 
    issue_server_link = https://issues.example.com/{repo}/issue/\1
 
    issue_sub =
 

	
 
``issue_pat`` is the regular expression describing which strings in
 
commit messages will be treated as issue references. The expression can/should
 
have one or more parenthesized groups that can later be referred to in
 
``issue_server_link`` and ``issue_sub`` (see below). If you prefer, named groups
 
can be used instead of simple parenthesized groups.
 

	
 
If the pattern should only match if it is preceded by whitespace, add the
 
following string before the actual pattern: ``(?:^|(?<=\s))``.
 
If the pattern should only match if it is followed by whitespace, add the
 
following string after the actual pattern: ``(?:$|(?=\s))``.
 
These expressions use lookbehind and lookahead assertions of the Python regular
 
expression module to avoid the whitespace to be part of the actual pattern,
 
otherwise the link text will also contain that whitespace.
 

	
 
Matched issue references are replaced with the link specified in
 
``issue_server_link``, in which any backreferences are resolved. Backreferences
 
can be ``\1``, ``\2``, ... or for named groups ``\g<groupname>``.
 
The special token ``{repo}`` is replaced with the full repository path
 
(including repository groups), while token ``{repo_name}`` is replaced with the
 
repository name (without repository groups).
 

	
 
The link text is determined by ``issue_sub``, which can be a string containing
 
backreferences to the groups specified in ``issue_pat``. If ``issue_sub`` is
kallithea/lib/paster_commands/template.ini.mako
Show inline comments
 
@@ -269,350 +269,350 @@ issue_sub =
 

	
 
#issue_pat_wiki = wiki-(\S+)
 
#issue_server_link_wiki = https://wiki.example.com/\1
 
#issue_sub_wiki = WIKI-\1
 

	
 
<%text>##</%text> alternative return HTTP header for failed authentication. Default HTTP
 
<%text>##</%text> response is 401 HTTPUnauthorized. Currently Mercurial clients have trouble with
 
<%text>##</%text> handling that. Set this variable to 403 to return HTTPForbidden
 
auth_ret_code =
 

	
 
<%text>##</%text> allows to change the repository location in settings page
 
allow_repo_location_change = True
 

	
 
<%text>##</%text> allows to setup custom hooks in settings page
 
allow_custom_hooks_settings = True
 

	
 
<%text>##</%text> extra extensions for indexing, space separated and without the leading '.'.
 
#index.extensions =
 
#    gemfile
 
#    lock
 

	
 
<%text>##</%text> extra filenames for indexing, space separated
 
#index.filenames =
 
#    .dockerignore
 
#    .editorconfig
 
#    INSTALL
 
#    CHANGELOG
 

	
 
<%text>##</%text>##################################
 
<%text>##</%text>            SSH CONFIG          ##
 
<%text>##</%text>##################################
 

	
 
<%text>##</%text> SSH is disabled by default, until an Administrator decides to enable it.
 
ssh_enabled = false
 

	
 
<%text>##</%text> File where users' SSH keys will be stored *if* ssh_enabled is true.
 
#ssh_authorized_keys = /home/kallithea/.ssh/authorized_keys
 
%if user_home_path:
 
ssh_authorized_keys = ${user_home_path}/.ssh/authorized_keys
 
%endif
 

	
 
<%text>##</%text> Path to be used in ssh_authorized_keys file to invoke kallithea-cli with ssh-serve.
 
#kallithea_cli_path = /srv/kallithea/venv/bin/kallithea-cli
 
%if kallithea_cli_path:
 
kallithea_cli_path = ${kallithea_cli_path}
 
%endif
 

	
 
<%text>##</%text> Locale to be used in the ssh-serve command.
 
<%text>##</%text> This is needed because an SSH client may try to use its own locale
 
<%text>##</%text> settings, which may not be available on the server.
 
<%text>##</%text> See `locale -a` for valid values on this system.
 
#ssh_locale = C.UTF-8
 
%if ssh_locale:
 
ssh_locale = ${ssh_locale}
 
%endif
 

	
 
<%text>##</%text>##################################
 
<%text>##</%text>         CELERY CONFIG          ##
 
<%text>##</%text>##################################
 

	
 
<%text>##</%text> Note: Celery doesn't support Windows.
 
use_celery = false
 

	
 
<%text>##</%text> Celery config settings from https://docs.celeryproject.org/en/4.4.0/userguide/configuration.html prefixed with 'celery.'.
 

	
 
<%text>##</%text> Example: use the message queue on the local virtual host 'kallitheavhost' as the RabbitMQ user 'kallithea':
 
celery.broker_url = amqp://kallithea:thepassword@localhost:5672/kallitheavhost
 

	
 
celery.result.backend = db+sqlite:///celery-results.db
 

	
 
#celery.amqp.task.result.expires = 18000
 

	
 
celery.worker_concurrency = 2
 
celery.worker_max_tasks_per_child = 1
 

	
 
<%text>##</%text> If true, tasks will never be sent to the queue, but executed locally instead.
 
celery.task_always_eager = false
 

	
 
<%text>##</%text>##################################
 
<%text>##</%text>          BEAKER CACHE          ##
 
<%text>##</%text>##################################
 

	
 
beaker.cache.data_dir = %(here)s/data/cache/data
 
beaker.cache.lock_dir = %(here)s/data/cache/lock
 

	
 
beaker.cache.regions = long_term,long_term_file
 

	
 
beaker.cache.long_term.type = memory
 
beaker.cache.long_term.expire = 36000
 
beaker.cache.long_term.key_length = 256
 

	
 
beaker.cache.long_term_file.type = file
 
beaker.cache.long_term_file.expire = 604800
 
beaker.cache.long_term_file.key_length = 256
 

	
 
<%text>##</%text>##################################
 
<%text>##</%text>        BEAKER SESSION          ##
 
<%text>##</%text>##################################
 

	
 
<%text>##</%text> Name of session cookie. Should be unique for a given host and path, even when running
 
<%text>##</%text> on different ports. Otherwise, cookie sessions will be shared and messed up.
 
session.key = kallithea
 
<%text>##</%text> Sessions should always only be accessible by the browser, not directly by JavaScript.
 
session.httponly = true
 
<%text>##</%text> Session lifetime. 2592000 seconds is 30 days.
 
session.timeout = 2592000
 

	
 
<%text>##</%text> Server secret used with HMAC to ensure integrity of cookies.
 
session.secret = ${uuid()}
 
<%text>##</%text> Further, encrypt the data with AES.
 
#session.encrypt_key = <key_for_encryption>
 
#session.validate_key = <validation_key>
 

	
 
<%text>##</%text> Type of storage used for the session, current types are
 
<%text>##</%text> dbm, file, memcached, database, and memory.
 

	
 
<%text>##</%text> File system storage of session data. (default)
 
#session.type = file
 

	
 
<%text>##</%text> Cookie only, store all session data inside the cookie. Requires secure secrets.
 
#session.type = cookie
 

	
 
<%text>##</%text> Database storage of session data.
 
#session.type = ext:database
 
#session.sa.url = postgresql://postgres:qwe@localhost/kallithea
 
#session.table_name = db_session
 

	
 
<%text>##</%text>##################################
 
<%text>##</%text>        ERROR HANDLING          ##
 
<%text>##</%text>##################################
 

	
 
<%text>##</%text> Show a nice error page for application HTTP errors and exceptions (default true)
 
#errorpage.enabled = true
 

	
 
<%text>##</%text> Enable Backlash client-side interactive debugger (default false)
 
<%text>##</%text> WARNING: *THIS MUST BE false IN PRODUCTION ENVIRONMENTS!!!*
 
<%text>##</%text> This debug mode will allow all visitors to execute malicious code.
 
#debug = false
 

	
 
<%text>##</%text> Enable Backlash server-side error reporting (unless debug mode handles it client-side) (default true)
 
#trace_errors.enable = true
 
<%text>##</%text> Errors will be reported by mail if trace_errors.error_email is set.
 

	
 
<%text>##</%text> Propagate email settings to ErrorReporter of TurboGears2
 
<%text>##</%text> You do not normally need to change these lines
 
get trace_errors.smtp_server = smtp_server
 
get trace_errors.smtp_port = smtp_port
 
get trace_errors.from_address = error_email_from
 
get trace_errors.error_email = email_to
 
get trace_errors.smtp_username = smtp_username
 
get trace_errors.smtp_password = smtp_password
 
get trace_errors.smtp_use_tls = smtp_use_tls
 

	
 
%if error_aggregation_service == 'sentry':
 
<%text>##</%text>##############
 
<%text>##</%text>  [sentry]  ##
 
<%text>##</%text>##############
 

	
 
<%text>##</%text> sentry is a alternative open source error aggregator
 
<%text>##</%text> you must install python packages `sentry` and `raven` to enable
 

	
 
sentry.dsn = YOUR_DNS
 
sentry.servers =
 
sentry.name =
 
sentry.key =
 
sentry.public_key =
 
sentry.secret_key =
 
sentry.project =
 
sentry.site =
 
sentry.include_paths =
 
sentry.exclude_paths =
 

	
 
%endif
 

	
 
<%text>##</%text>################################
 
<%text>##</%text>        LOGVIEW CONFIG        ##
 
<%text>##</%text>################################
 

	
 
logview.sqlalchemy = #faa
 
logview.pylons.templating = #bfb
 
logview.pylons.util = #eee
 

	
 
<%text>##</%text>#######################
 
<%text>##</%text>      DB CONFIG      ##
 
<%text>##</%text>#######################
 

	
 
%if database_engine == 'sqlite':
 
sqlalchemy.url = sqlite:///%(here)s/kallithea.db?timeout=60
 
%else:
 
#sqlalchemy.url = sqlite:///%(here)s/kallithea.db?timeout=60
 
%endif
 
%if database_engine == 'postgres':
 
sqlalchemy.url = postgresql://user:pass@localhost/kallithea
 
sqlalchemy.url = postgresql://kallithea:password@localhost/kallithea
 
%else:
 
#sqlalchemy.url = postgresql://user:pass@localhost/kallithea
 
#sqlalchemy.url = postgresql://kallithea:password@localhost/kallithea
 
%endif
 
%if database_engine == 'mysql':
 
sqlalchemy.url = mysql://user:pass@localhost/kallithea?charset=utf8
 
sqlalchemy.url = mysql://kallithea:password@localhost/kallithea?charset=utf8
 
%else:
 
#sqlalchemy.url = mysql://user:pass@localhost/kallithea?charset=utf8
 
#sqlalchemy.url = mysql://kallithea:password@localhost/kallithea?charset=utf8
 
%endif
 
<%text>##</%text> Note: the mysql:// prefix should also be used for MariaDB
 

	
 
sqlalchemy.pool_recycle = 3600
 

	
 
<%text>##</%text>##############################
 
<%text>##</%text>   ALEMBIC CONFIGURATION    ##
 
<%text>##</%text>##############################
 

	
 
[alembic]
 
script_location = kallithea:alembic
 

	
 
<%text>##</%text>##############################
 
<%text>##</%text>   LOGGING CONFIGURATION    ##
 
<%text>##</%text>##############################
 

	
 
[loggers]
 
keys = root, routes, kallithea, sqlalchemy, tg, gearbox, beaker, templates, whoosh_indexer, werkzeug, backlash
 

	
 
[handlers]
 
keys = console, console_color, console_color_sql, null
 

	
 
[formatters]
 
keys = generic, color_formatter, color_formatter_sql
 

	
 
<%text>##</%text>###########
 
<%text>##</%text> LOGGERS ##
 
<%text>##</%text>###########
 

	
 
[logger_root]
 
level = NOTSET
 
handlers = console
 
<%text>##</%text> For coloring based on log level:
 
#handlers = console_color
 

	
 
[logger_routes]
 
level = WARN
 
handlers =
 
qualname = routes.middleware
 
<%text>##</%text> "level = DEBUG" logs the route matched and routing variables.
 

	
 
[logger_beaker]
 
level = WARN
 
handlers =
 
qualname = beaker.container
 

	
 
[logger_templates]
 
level = WARN
 
handlers =
 
qualname = pylons.templating
 

	
 
[logger_kallithea]
 
level = WARN
 
handlers =
 
qualname = kallithea
 

	
 
[logger_tg]
 
level = WARN
 
handlers =
 
qualname = tg
 

	
 
[logger_gearbox]
 
level = WARN
 
handlers =
 
qualname = gearbox
 

	
 
[logger_sqlalchemy]
 
level = WARN
 
handlers =
 
qualname = sqlalchemy.engine
 
<%text>##</%text> For coloring based on log level and pretty printing of SQL:
 
#level = INFO
 
#handlers = console_color_sql
 
#propagate = 0
 

	
 
[logger_whoosh_indexer]
 
level = WARN
 
handlers =
 
qualname = whoosh_indexer
 

	
 
[logger_werkzeug]
 
level = WARN
 
handlers =
 
qualname = werkzeug
 

	
 
[logger_backlash]
 
level = WARN
 
handlers =
 
qualname = backlash
 

	
 
<%text>##</%text>############
 
<%text>##</%text> HANDLERS ##
 
<%text>##</%text>############
 

	
 
[handler_console]
 
class = StreamHandler
 
args = (sys.stderr,)
 
formatter = generic
 

	
 
[handler_console_color]
 
<%text>##</%text> ANSI color coding based on log level
 
class = StreamHandler
 
args = (sys.stderr,)
 
formatter = color_formatter
 

	
 
[handler_console_color_sql]
 
<%text>##</%text> ANSI color coding and pretty printing of SQL statements
 
class = StreamHandler
 
args = (sys.stderr,)
 
formatter = color_formatter_sql
 

	
 
[handler_null]
 
class = NullHandler
 
args = ()
 

	
 
<%text>##</%text>##############
 
<%text>##</%text> FORMATTERS ##
 
<%text>##</%text>##############
 

	
 
[formatter_generic]
 
format = %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s
 
datefmt = %Y-%m-%d %H:%M:%S
 

	
 
[formatter_color_formatter]
 
class = kallithea.lib.colored_formatter.ColorFormatter
 
format = %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s
 
datefmt = %Y-%m-%d %H:%M:%S
 

	
 
[formatter_color_formatter_sql]
 
class = kallithea.lib.colored_formatter.ColorFormatterSql
 
format = %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s
 
datefmt = %Y-%m-%d %H:%M:%S
 

	
 
<%text>##</%text>###############
 
<%text>##</%text> SSH LOGGING ##
 
<%text>##</%text>###############
 

	
 
<%text>##</%text> The default loggers use 'handler_console' that uses StreamHandler with
 
<%text>##</%text> destination 'sys.stderr'. In the context of the SSH server process, these log
 
<%text>##</%text> messages would be sent to the client, which is normally not what you want.
 
<%text>##</%text> By default, when running ssh-serve, just use NullHandler and disable logging
 
<%text>##</%text> completely. For other logging options, see:
 
<%text>##</%text> https://docs.python.org/2/library/logging.handlers.html
 

	
 
[ssh_serve:logger_root]
 
level = CRITICAL
 
handlers = null
 

	
 
<%text>##</%text> Note: If logging is configured with other handlers, they might need similar
 
<%text>##</%text> muting for ssh-serve too.
0 comments (0 inline, 0 general)