kallithea: docs/setup.rst annotate

annotate docs/setup.rst @ 8612:4d742b172010

docs: front-end-build is actually a part of the install process - it is shared among all the instances

author	Mads Kiilerich <mads@kiilerich.com>
date	Thu, 13 Aug 2020 19:04:00 +0200
parents	7a1371d659c5
children	c354d1a7537f

rev	line source
568 5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	1 .. _setup:
5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	2
2095 17c9393e9645 docs Marcin Kuzminski <marcin@python-works.com> parents: 2076 diff changeset	3 =====
568 5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	4 Setup
5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	5 =====
5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	6
5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	7
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	8 Setting up Kallithea
1448 b05eb16ea105 fixes #206 Marcin Kuzminski <marcin@python-works.com> parents: 1420 diff changeset	9 --------------------
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	10
8576 a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview Mads Kiilerich <mads@kiilerich.com> parents: 8444 diff changeset	11 Some further details to the steps mentioned in the overview.
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview Mads Kiilerich <mads@kiilerich.com> parents: 8444 diff changeset	12
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview Mads Kiilerich <mads@kiilerich.com> parents: 8444 diff changeset	13 Create low level configuration file
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview Mads Kiilerich <mads@kiilerich.com> parents: 8444 diff changeset	14 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview Mads Kiilerich <mads@kiilerich.com> parents: 8444 diff changeset	15
8578 ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	16 First, you will need to create a Kallithea configuration file. The
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	17 configuration file is a ``.ini`` file that contains various low level settings
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	18 for Kallithea, e.g. configuration of how to use database, web server, email,
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	19 and logging.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	20
8578 ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	21 Run the following command to create the file ``my.ini`` in the current
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	22 directory::
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	23
8578 ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	24 kallithea-cli config-create my.ini http_server=waitress
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	25
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	26 To get a good starting point for your configuration, specify the http server
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	27 you intend to use. It can be ``waitress``, ``gearbox``, ``gevent``,
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	28 ``gunicorn``, or ``uwsgi``. (Apache ``mod_wsgi`` will not use this
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	29 configuration file, and it is fine to keep the default http_server configuration
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	30 unused. ``mod_wsgi`` is configured using ``httpd.conf`` directives and a WSGI
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	31 wrapper script.)
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	32
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	33 Extra custom settings can be specified like::
6898 a8b9f2d68e7d make-config: allow configuration of any ini value Mads Kiilerich <mads@kiilerich.com> parents: 6789 diff changeset	34
7406 7784a1212471 cli: convert 'gearbox make-config' into 'kallithea-cli config-create' Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7389 diff changeset	35 kallithea-cli config-create my.ini host=8.8.8.8 "[handler_console]" formatter=color_formatter
845 a040597b070b docs update Marcin Kuzminski <marcin@python-works.com> parents: 777 diff changeset	36
8576 a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview Mads Kiilerich <mads@kiilerich.com> parents: 8444 diff changeset	37 Populate the database
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview Mads Kiilerich <mads@kiilerich.com> parents: 8444 diff changeset	38 ^^^^^^^^^^^^^^^^^^^^^
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview Mads Kiilerich <mads@kiilerich.com> parents: 8444 diff changeset	39
8578 ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	40 Next, you need to create the databases used by Kallithea. Kallithea currently
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	41 supports PostgreSQL, SQLite and MariaDB/MySQL databases. It is recommended to
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	42 start out using SQLite (the default) and move to PostgreSQL if it becomes a
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	43 bottleneck or to get a "proper" database. MariaDB/MySQL is also supported.
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	44
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	45 For PostgreSQL, run ``pip install psycopg2`` to get the database driver. Make
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	46 sure the PostgreSQL server is initialized and running. Make sure you have a
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	47 database user with password authentication with permissions to create databases
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	48 - for example by running::
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	49
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	50 sudo -u postgres createuser 'kallithea' --pwprompt --createdb
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	51
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	52 For MariaDB/MySQL, run ``pip install mysqlclient`` to get the ``MySQLdb``
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	53 database driver. Make sure the database server is initialized and running. Make
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	54 sure you have a database user with password authentication with permissions to
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	55 create the database - for example by running::
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	56
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	57 echo 'CREATE USER "kallithea"@"localhost" IDENTIFIED BY "password"' \| sudo -u mysql mysql
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	58 echo 'GRANT ALL PRIVILEGES ON `kallithea`.* TO "kallithea"@"localhost"' \| sudo -u mysql mysql
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	59
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	60 Check and adjust ``sqlalchemy.url`` in your ``my.ini`` configuration file to use
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	61 this database.
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	62
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	63 Create the database, tables, and initial content by running the following
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	64 command::
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	65
7414 3158cf0dafb7 cli: convert 'gearbox setup-db' into 'kallithea-cli db-create' Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7406 diff changeset	66 kallithea-cli db-create -c my.ini
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	67
8577 4742b8c89472 docs: drop odd verbose note on writeable root path Mads Kiilerich <mads@kiilerich.com> parents: 8576 diff changeset	68 This will first prompt you for a "root" path. This "root" path is the location
4742b8c89472 docs: drop odd verbose note on writeable root path Mads Kiilerich <mads@kiilerich.com> parents: 8576 diff changeset	69 where Kallithea will store all of its repositories on the current machine. This
4742b8c89472 docs: drop odd verbose note on writeable root path Mads Kiilerich <mads@kiilerich.com> parents: 8576 diff changeset	70 location must be writable for the running Kallithea application. Next,
4742b8c89472 docs: drop odd verbose note on writeable root path Mads Kiilerich <mads@kiilerich.com> parents: 8576 diff changeset	71 ``db-create`` will prompt you for a username and password for the initial admin
4742b8c89472 docs: drop odd verbose note on writeable root path Mads Kiilerich <mads@kiilerich.com> parents: 8576 diff changeset	72 account it sets up for you.
845 a040597b070b docs update Marcin Kuzminski <marcin@python-works.com> parents: 777 diff changeset	73
7414 3158cf0dafb7 cli: convert 'gearbox setup-db' into 'kallithea-cli db-create' Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7406 diff changeset	74 The ``db-create`` values can also be given on the command line.
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	75 Example::
2358 69df04ee1e2b added detailed step-by-step installation instruction for windows Marcin Kuzminski <marcin@python-works.com> parents: 2284 diff changeset	76
7414 3158cf0dafb7 cli: convert 'gearbox setup-db' into 'kallithea-cli db-create' Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7406 diff changeset	77 kallithea-cli db-create -c my.ini --user=nn --password=secret --email=nn@example.com --repos=/srv/repos
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	78
7414 3158cf0dafb7 cli: convert 'gearbox setup-db' into 'kallithea-cli db-create' Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7406 diff changeset	79 The ``db-create`` command will create all needed tables and an
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	80 admin account. When choosing a root path you can either use a new
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	81 empty location, or a location which already contains existing
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	82 repositories. If you choose a location which contains existing
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	83 repositories Kallithea will add all of the repositories at the chosen
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	84 location to its database. (Note: make sure you specify the correct
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	85 path to the root).
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	86
8592 307c876a6e89 db: introduce db-create --reuse option Mads Kiilerich <mads@kiilerich.com> parents: 8578 diff changeset	87 .. note:: It is also possible to use an existing database. For example,
307c876a6e89 db: introduce db-create --reuse option Mads Kiilerich <mads@kiilerich.com> parents: 8578 diff changeset	88 when using PostgreSQL without granting general createdb privileges to
307c876a6e89 db: introduce db-create --reuse option Mads Kiilerich <mads@kiilerich.com> parents: 8578 diff changeset	89 the PostgreSQL kallithea user, set ``sqlalchemy.url =
307c876a6e89 db: introduce db-create --reuse option Mads Kiilerich <mads@kiilerich.com> parents: 8578 diff changeset	90 postgresql://kallithea:password@localhost/kallithea`` and create the
307c876a6e89 db: introduce db-create --reuse option Mads Kiilerich <mads@kiilerich.com> parents: 8578 diff changeset	91 database like::
307c876a6e89 db: introduce db-create --reuse option Mads Kiilerich <mads@kiilerich.com> parents: 8578 diff changeset	92
307c876a6e89 db: introduce db-create --reuse option Mads Kiilerich <mads@kiilerich.com> parents: 8578 diff changeset	93 sudo -u postgres createdb 'kallithea' --owner 'kallithea'
307c876a6e89 db: introduce db-create --reuse option Mads Kiilerich <mads@kiilerich.com> parents: 8578 diff changeset	94 kallithea-cli db-create -c my.ini --reuse
307c876a6e89 db: introduce db-create --reuse option Mads Kiilerich <mads@kiilerich.com> parents: 8578 diff changeset	95
8576 a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview Mads Kiilerich <mads@kiilerich.com> parents: 8444 diff changeset	96 Running
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview Mads Kiilerich <mads@kiilerich.com> parents: 8444 diff changeset	97 ^^^^^^^
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview Mads Kiilerich <mads@kiilerich.com> parents: 8444 diff changeset	98
8578 ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	99 You are now ready to use Kallithea. To run it using a gearbox web server,
ff8651b2f14f docs: augment setup description with more details of http server and database Mads Kiilerich <mads@kiilerich.com> parents: 8577 diff changeset	100 simply execute::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	101
6554 2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack Mads Kiilerich <madski@unity3d.com> parents: 6457 diff changeset	102 gearbox serve -c my.ini
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	103
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	104 - This command runs the Kallithea server. The web app should be available at
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	105 http://127.0.0.1:5000. The IP address and port is configurable via the
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	106 configuration file created in the previous step.
7414 3158cf0dafb7 cli: convert 'gearbox setup-db' into 'kallithea-cli db-create' Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7406 diff changeset	107 - Log in to Kallithea using the admin account created when running ``db-create``.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	108 - The default permissions on each repository is read, and the owner is admin.
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	109 Remember to update these if needed.
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	110 - In the admin panel you can toggle LDAP, anonymous, and permissions
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	111 settings, as well as edit more advanced options on users and
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	112 repositories.
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	113
5077 faf943716616 rcextensions: cleanup of code and documentation Mads Kiilerich <madski@unity3d.com> parents: 4955 diff changeset	114
6695 8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	115 Internationalization (i18n support)
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	116 -----------------------------------
2105 926f55b038bc added initial rc-extension module Marcin Kuzminski <marcin@python-works.com> parents: 2095 diff changeset	117
6695 8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	118 The Kallithea web interface is automatically displayed in the user's preferred
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	119 language, as indicated by the browser. Thus, different users may see the
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	120 application in different languages. If the requested language is not available
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	121 (because the translation file for that language does not yet exist or is
8095 7c7d6b5c07c7 i18n: make sure 'en' in Accept-Language is recognized as having 100% coverage - i18n.lang is for source language Mads Kiilerich <mads@kiilerich.com> parents: 8086 diff changeset	122 incomplete), English is used.
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	123
6695 8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	124 If you want to disable automatic language detection and instead configure a
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	125 fixed language regardless of user preference, set ``i18n.enabled = false`` and
8095 7c7d6b5c07c7 i18n: make sure 'en' in Accept-Language is recognized as having 100% coverage - i18n.lang is for source language Mads Kiilerich <mads@kiilerich.com> parents: 8086 diff changeset	126 specify another language by setting ``i18n.lang`` in the Kallithea
7c7d6b5c07c7 i18n: make sure 'en' in Accept-Language is recognized as having 100% coverage - i18n.lang is for source language Mads Kiilerich <mads@kiilerich.com> parents: 8086 diff changeset	127 configuration file.
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	128
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	129
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	130 Using Kallithea with SSH
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	131 ------------------------
8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	132
7783 e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	133 Kallithea supports repository access via SSH key based authentication.
7829 ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	134 This means:
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	135
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	136 - repository URLs like ``ssh://kallithea@example.com/name/of/repository``
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	137
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	138 - all network traffic for both read and write happens over the SSH protocol on
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	139 port 22, without using HTTP/HTTPS nor the Kallithea WSGI application
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	140
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	141 - encryption and authentication protocols are managed by the system's ``sshd``
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	142 process, with all users using the same Kallithea system user (e.g.
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	143 ``kallithea``) when connecting to the SSH server, but with users' public keys
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	144 in the Kallithea system user's `.ssh/authorized_keys` file granting each user
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	145 sandboxed access to the repositories.
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	146
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	147 - users and admins can manage SSH public keys in the web UI
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	148
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	149 - in their SSH client configuration, users can configure how the client should
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	150 control access to their SSH key - without passphrase, with passphrase, and
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	151 optionally with passphrase caching in the local shell session (``ssh-agent``).
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	152 This is standard SSH functionality, not something Kallithea provides or
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	153 interferes with.
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	154
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	155 - network communication between client and server happens in a bidirectional
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	156 stateful stream, and will in some cases be faster than HTTP/HTTPS with several
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	157 stateless round-trips.
ee4fc2d20d09 docs: add high-level description of SSH repository access Mads Kiilerich <mads@kiilerich.com> parents: 7783 diff changeset	158
7783 e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	159 .. note:: At this moment, repository access via SSH has been tested on Unix
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	160 only. Windows users that care about SSH are invited to test it and report
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	161 problems, ideally contributing patches that solve these problems.
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	162
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	163 Users and admins can upload SSH public keys (e.g. ``.ssh/id_rsa.pub``) through
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	164 the web interface. The server's ``.ssh/authorized_keys`` file is automatically
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	165 maintained with an entry for each SSH key. Each entry will tell ``sshd`` to run
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	166 ``kallithea-cli`` with the ``ssh-serve`` sub-command and the right Kallithea user ID
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	167 when encountering the corresponding SSH key.
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	168
7783 e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	169 To enable SSH repository access, Kallithea must be configured with the path to
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	170 the ``.ssh/authorized_keys`` file for the Kallithea user, and the path to the
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	171 ``kallithea-cli`` command. Put something like this in the ``.ini`` file::
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	172
7783 e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	173 ssh_enabled = true
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	174 ssh_authorized_keys = /home/kallithea/.ssh/authorized_keys
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	175 kallithea_cli_path = /srv/kallithea/venv/bin/kallithea-cli
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	176
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	177 The SSH service must be running, and the Kallithea user account must be active
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	178 (not necessarily with password access, but public key access must be enabled),
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	179 all file permissions must be set as sshd wants it, and ``authorized_keys`` must
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	180 be writeable by the Kallithea user.
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	181
7783 e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	182 .. note:: The ``authorized_keys`` file will be rewritten from scratch on
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	183 each update. If it already exists with other data, Kallithea will not
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	184 overwrite the existing ``authorized_keys``, and the server process will
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	185 instead throw an exception. The system administrator thus cannot ssh
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	186 directly to the Kallithea user but must use su/sudo from another account.
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	187
7783 e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	188 If ``/home/kallithea/.ssh/`` (the directory of the path specified in the
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	189 ``ssh_authorized_keys`` setting of the ``.ini`` file) does not exist as a
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	190 directory, Kallithea will attempt to create it. If that path exists but is
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	191 not a directory, or is not readable-writable-executable by the server
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	192 process, the server process will raise an exception each time it attempts to
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	193 write the ``authorized_keys`` file.
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	194
8372 a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files Mads Kiilerich <mads@kiilerich.com> parents: 8268 diff changeset	195 .. note:: It is possible to configure the SSH server to look for authorized
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files Mads Kiilerich <mads@kiilerich.com> parents: 8268 diff changeset	196 keys in multiple files, for example reserving ``ssh/authorized_keys`` to be
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files Mads Kiilerich <mads@kiilerich.com> parents: 8268 diff changeset	197 used for normal SSH and with Kallithea using
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files Mads Kiilerich <mads@kiilerich.com> parents: 8268 diff changeset	198 ``.ssh/authorized_keys_kallithea``. In ``/etc/ssh/sshd_config`` set
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files Mads Kiilerich <mads@kiilerich.com> parents: 8268 diff changeset	199 ``AuthorizedKeysFile .ssh/authorized_keys .ssh/authorized_keys_kallithea``
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files Mads Kiilerich <mads@kiilerich.com> parents: 8268 diff changeset	200 and restart sshd, and in ``my.ini`` set ``ssh_authorized_keys =
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files Mads Kiilerich <mads@kiilerich.com> parents: 8268 diff changeset	201 /home/kallithea/.ssh/authorized_keys_kallithea``. Note that this new
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files Mads Kiilerich <mads@kiilerich.com> parents: 8268 diff changeset	202 location will apply to all system users, and that multiple entries for the
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files Mads Kiilerich <mads@kiilerich.com> parents: 8268 diff changeset	203 same SSH key will shadow each other.
a9e71e61cedf ssh: mention in docs how to use multiple authorized_keys files Mads Kiilerich <mads@kiilerich.com> parents: 8268 diff changeset	204
7783 e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	205 .. warning:: The handling of SSH access is steered directly by the command
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	206 specified in the ``authorized_keys`` file. There is no interaction with the
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	207 web UI. Once SSH access is correctly configured and enabled, it will work
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	208 regardless of whether the Kallithea web process is actually running. Hence,
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	209 if you want to perform repository or server maintenance and want to fully
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	210 disable all access to the repositories, disable SSH access by setting
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	211 ``ssh_enabled = false`` in the correct ``.ini`` file (i.e. the ``.ini`` file
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	212 specified in the ``authorized_keys`` file.)
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	213
7783 e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	214 The ``authorized_keys`` file can be updated manually with ``kallithea-cli
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	215 ssh-update-authorized-keys -c my.ini``. This command is not needed in normal
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	216 operation but is for example useful after changing SSH-related settings in the
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	217 ``.ini`` file or renaming that file. (The path to the ``.ini`` file is used in
e4f27ab7cbea ssh: add documentation of SSH support Christian Oyarzun <oyarzun@gmail.com> parents: 7653 diff changeset	218 the generated ``authorized_keys`` file).
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	219
5433 fbbe80e3322b docs: consistent spacing around headings Mads Kiilerich <madski@unity3d.com> parents: 5426 diff changeset	220
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	221 Setting up Whoosh full text search
341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	222 ----------------------------------
341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	223
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	224 Kallithea provides full text search of repositories using `Whoosh`__.
894 1fed3c9161bb fixes #90 + docs update Marcin Kuzminski <marcin@python-works.com> parents: 881 diff changeset	225
8604 61bd04b90f58 docs: clean up readthedocs URLs Mads Kiilerich <mads@kiilerich.com> parents: 8592 diff changeset	226 .. __: https://whoosh.readthedocs.io/
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	227
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	228 For an incremental index build, run::
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	229
7416 502b9bd0a24d cli: convert 'gearbox make-index' into 'kallithea-cli index-create' Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7414 diff changeset	230 kallithea-cli index-create -c my.ini
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	231
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	232 For a full index rebuild, run::
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	233
7416 502b9bd0a24d cli: convert 'gearbox make-index' into 'kallithea-cli index-create' Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7414 diff changeset	234 kallithea-cli index-create -c my.ini --full
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	235
5855 1048307eb1f5 spelling: overridden timeless@gmail.com parents: 5832 diff changeset	236 The ``--repo-location`` option allows the location of the repositories to be overridden;
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	237 usually, the location is retrieved from the Kallithea database.
894 1fed3c9161bb fixes #90 + docs update Marcin Kuzminski <marcin@python-works.com> parents: 881 diff changeset	238
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	239 The ``--index-only`` option can be used to limit the indexed repositories to a comma-separated list::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	240
7416 502b9bd0a24d cli: convert 'gearbox make-index' into 'kallithea-cli index-create' Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7414 diff changeset	241 kallithea-cli index-create -c my.ini --index-only=vcs,kallithea
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	242
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	243 To keep your index up-to-date it is necessary to do periodic index builds;
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	244 for this, it is recommended to use a crontab entry. Example::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	245
7416 502b9bd0a24d cli: convert 'gearbox make-index' into 'kallithea-cli index-create' Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7414 diff changeset	246 0 3 * * * /path/to/virtualenv/bin/kallithea-cli index-create -c /path/to/kallithea/my.ini
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	247
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	248 When using incremental mode (the default), Whoosh will check the last
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	249 modification date of each file and add it to be reindexed if a newer file is
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	250 available. The indexing daemon checks for any removed files and removes them
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	251 from index.
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	252
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	253 If you want to rebuild the index from scratch, you can use the ``-f`` flag as above,
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	254 or in the admin panel you can check the "build from scratch" checkbox.
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	255
5413 22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings Mads Kiilerich <madski@unity3d.com> parents: 5412 diff changeset	256
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings Mads Kiilerich <madski@unity3d.com> parents: 5412 diff changeset	257 Integration with issue trackers
1838 2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	258 -------------------------------
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	259
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	260 Kallithea provides a simple integration with issue trackers. It's possible
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	261 to define a regular expression that will match an issue ID in commit messages,
7230 d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	262 and have that replaced with a URL to the issue.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	263
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	264 This is achieved with following three variables in the ini file::
1838 2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	265
7230 d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	266 issue_pat = #(\d+)
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	267 issue_server_link = https://issues.example.com/{repo}/issue/\1
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	268 issue_sub =
1838 2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	269
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	270 ``issue_pat`` is the regular expression describing which strings in
7230 d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	271 commit messages will be treated as issue references. The expression can/should
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	272 have one or more parenthesized groups that can later be referred to in
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	273 ``issue_server_link`` and ``issue_sub`` (see below). If you prefer, named groups
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	274 can be used instead of simple parenthesized groups.
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	275
7230 d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	276 If the pattern should only match if it is preceded by whitespace, add the
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	277 following string before the actual pattern: ``(?:^\|(?<=\s))``.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	278 If the pattern should only match if it is followed by whitespace, add the
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	279 following string after the actual pattern: ``(?:$\|(?=\s))``.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	280 These expressions use lookbehind and lookahead assertions of the Python regular
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	281 expression module to avoid the whitespace to be part of the actual pattern,
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	282 otherwise the link text will also contain that whitespace.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	283
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	284 Matched issue references are replaced with the link specified in
7230 d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	285 ``issue_server_link``, in which any backreferences are resolved. Backreferences
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	286 can be ``\1``, ``\2``, ... or for named groups ``\g<groupname>``.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	287 The special token ``{repo}`` is replaced with the full repository path
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	288 (including repository groups), while token ``{repo_name}`` is replaced with the
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	289 repository name (without repository groups).
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	290
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	291 The link text is determined by ``issue_sub``, which can be a string containing
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	292 backreferences to the groups specified in ``issue_pat``. If ``issue_sub`` is
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	293 empty, then the text matched by ``issue_pat`` is used verbatim.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	294
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	295 The example settings shown above match issues in the format ``#<number>``.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	296 This will cause the text ``#300`` to be transformed into a link:
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	297
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	298 .. code-block:: html
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	299
7230 d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	300 <a href="https://issues.example.com/example_repo/issue/300">#300</a>
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	301
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	302 The following example transforms a text starting with either of 'pullrequest',
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	303 'pull request' or 'PR', followed by an optional space, then a pound character
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	304 (#) and one or more digits, into a link with the text 'PR #' followed by the
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	305 digits::
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	306
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	307 issue_pat = (pullrequest\|pull request\|PR) ?#(\d+)
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	308 issue_server_link = https://issues.example.com/\2
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	309 issue_sub = PR #\2
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	310
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	311 The following example demonstrates how to require whitespace before the issue
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	312 reference in order for it to be recognized, such that the text ``issue#123`` will
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	313 not cause a match, but ``issue #123`` will::
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	314
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	315 issue_pat = (?:^\|(?<=\s))#(\d+)
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	316 issue_server_link = https://issues.example.com/\1
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	317 issue_sub =
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	318
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	319 If needed, more than one pattern can be specified by appending a unique suffix to
7230 d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	320 the variables. For example, also demonstrating the use of named groups::
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	321
7230 d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	322 issue_pat_wiki = wiki-(?P<pagename>\S+)
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	323 issue_server_link_wiki = https://wiki.example.com/\g<pagename>
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	324 issue_sub_wiki = WIKI-\g<pagename>
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	325
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	326 With these settings, wiki pages can be referenced as wiki-some-id, and every
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	327 such reference will be transformed into:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	328
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	329 .. code-block:: html
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	330
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	331 <a href="https://wiki.example.com/some-id">WIKI-some-id</a>
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	332
7230 d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	333 Refer to the `Python regular expression documentation`_ for more details about
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	334 the supported syntax in ``issue_pat``, ``issue_server_link`` and ``issue_sub``.
d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	335
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	336
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	337 Hook management
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	338 ---------------
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	339
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	340 Hooks can be managed in similar way to that used in ``.hgrc`` files.
5426 66f1b9745905 docs: update menu navigation notation to use Menu > Menu Item Søren Løvborg <sorenl@unity3d.com> parents: 5425 diff changeset	341 To manage hooks, choose Admin > Settings > Hooks.
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	342
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	343 The built-in hooks cannot be modified, though they can be enabled or disabled in the VCS section.
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	344
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	345 To add another custom hook simply fill in the first textbox with
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	346 ``<name>.<hook_type>`` and the second with the hook path. Example hooks
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	347 can be found in ``kallithea.lib.hooks``.
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	348
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	349
2017 03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	350 Changing default encoding
03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	351 -------------------------
03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	352
4914 95fe05b1e5f8 docs: better capitalisation Andrew Shadura <andrew@shadura.me> parents: 4902 diff changeset	353 By default, Kallithea uses UTF-8 encoding.
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	354 This is configurable as ``default_encoding`` in the .ini file.
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	355 This affects many parts in Kallithea including user names, filenames, and
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	356 encoding of commit messages. In addition Kallithea can detect if the ``chardet``
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	357 library is installed. If ``chardet`` is detected Kallithea will fallback to it
2017 03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	358 when there are encode/decode errors.
03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	359
7327 9937ae52f167 hg: set encoding to utf-8 by default to always show unicode characters correctly Mads Kiilerich <mads@kiilerich.com> parents: 7230 diff changeset	360 The Mercurial encoding is configurable as ``hgencoding``. It is similar to
9937ae52f167 hg: set encoding to utf-8 by default to always show unicode characters correctly Mads Kiilerich <mads@kiilerich.com> parents: 7230 diff changeset	361 setting the ``HGENCODING`` environment variable, but will override it.
9937ae52f167 hg: set encoding to utf-8 by default to always show unicode characters correctly Mads Kiilerich <mads@kiilerich.com> parents: 7230 diff changeset	362
2017 03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	363
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	364 Celery configuration
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	365 --------------------
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	366
4925 56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	367 Kallithea can use the distributed task queue system Celery_ to run tasks like
5412 2079e864ce51 spelling: use "email" consistently Søren Løvborg <sorenl@unity3d.com> parents: 5077 diff changeset	368 cloning repositories or sending emails.
4925 56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	369
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	370 Kallithea will in most setups work perfectly fine out of the box (without
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	371 Celery), executing all tasks in the web server process. Some tasks can however
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	372 take some time to run and it can be better to run such tasks asynchronously in
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	373 a separate process so the web server can focus on serving web requests.
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	374
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	375 For installation and configuration of Celery, see the `Celery documentation`_.
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	376 Note that Celery requires a message broker service like RabbitMQ_ (recommended)
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	377 or Redis_.
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	378
4925 56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	379 The use of Celery is configured in the Kallithea ini configuration file.
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	380 To enable it, simply set::
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	381
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	382 use_celery = true
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	383
8268 f8f50d3b6512 celery: upgrade to Celery 4 Mads Kiilerich <mads@kiilerich.com> parents: 8209 diff changeset	384 and add or change the ``celery.*`` configuration variables.
4925 56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	385
8268 f8f50d3b6512 celery: upgrade to Celery 4 Mads Kiilerich <mads@kiilerich.com> parents: 8209 diff changeset	386 Configuration settings are prefixed with 'celery.', so for example setting
f8f50d3b6512 celery: upgrade to Celery 4 Mads Kiilerich <mads@kiilerich.com> parents: 8209 diff changeset	387 `broker_url` in Celery means setting `celery.broker_url` in the configuration
f8f50d3b6512 celery: upgrade to Celery 4 Mads Kiilerich <mads@kiilerich.com> parents: 8209 diff changeset	388 file.
4925 56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	389
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	390 To start the Celery process, run::
938 442ccfe939d0 fixed changelog, and setup docs. Yeeee a 1000 commit :) Marcin Kuzminski <marcin@python-works.com> parents: 929 diff changeset	391
7417 1d539bb18165 cli: convert 'gearbox celeryd' into 'kallithea-cli celery-run' Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7416 diff changeset	392 kallithea-cli celery-run -c my.ini
6554 2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack Mads Kiilerich <madski@unity3d.com> parents: 6457 diff changeset	393
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack Mads Kiilerich <madski@unity3d.com> parents: 6457 diff changeset	394 Extra options to the Celery worker can be passed after ``--`` - see ``-- -h``
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack Mads Kiilerich <madski@unity3d.com> parents: 6457 diff changeset	395 for more info.
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	396
871 7f9e006aa26f docs update for celeryd Marcin Kuzminski <marcin@python-works.com> parents: 845 diff changeset	397 .. note::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	398 Make sure you run this command from the same virtualenv, and with the same
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	399 user that Kallithea runs.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	400
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	401
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	402 HTTPS support
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	403 -------------
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	404
4448 8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	405 Kallithea will by default generate URLs based on the WSGI environment.
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	406
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	407 Alternatively, you can use some special configuration settings to control
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	408 directly which scheme/protocol Kallithea will use when generating URLs:
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	409
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	410 - With ``https_fixup = true``, the scheme will be taken from the
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	411 ``X-Url-Scheme``, ``X-Forwarded-Scheme`` or ``X-Forwarded-Proto`` HTTP header
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	412 (default ``http``).
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	413 - With ``force_https = true`` the default will be ``https``.
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	414 - With ``use_htsts = true``, Kallithea will set ``Strict-Transport-Security`` when using https.
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	415
7340 2898ea3ff76c docs: move authentication info to separate file Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7337 diff changeset	416 .. _nginx_virtual_host:
2898ea3ff76c docs: move authentication info to separate file Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7337 diff changeset	417
871 7f9e006aa26f docs update for celeryd Marcin Kuzminski <marcin@python-works.com> parents: 845 diff changeset	418
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	419 Nginx virtual host example
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	420 --------------------------
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	421
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	422 Sample config for Nginx using proxy:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	423
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	424 .. code-block:: nginx
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	425
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	426 upstream kallithea {
1745 456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	427 server 127.0.0.1:5000;
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	428 # add more instances for load balancing
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	429 #server 127.0.0.1:5001;
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	430 #server 127.0.0.1:5002;
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	431 }
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	432
3850 7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	433 ## gist alias
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	434 server {
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	435 listen 443;
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	436 server_name gist.example.com;
3850 7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	437 access_log /var/log/nginx/gist.access.log;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	438 error_log /var/log/nginx/gist.error.log;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	439
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	440 ssl on;
4182 05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	441 ssl_certificate gist.your.kallithea.server.crt;
05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	442 ssl_certificate_key gist.your.kallithea.server.key;
3850 7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	443
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	444 ssl_session_timeout 5m;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	445
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	446 ssl_protocols SSLv3 TLSv1;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	447 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;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	448 ssl_prefer_server_ciphers on;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	449
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	450 rewrite ^/(.+)$ https://kallithea.example.com/_admin/gists/$1;
12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	451 rewrite (.*) https://kallithea.example.com/_admin/gists;
3850 7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	452 }
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	453
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	454 server {
3243 c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	455 listen 443;
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	456 server_name kallithea.example.com
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	457 access_log /var/log/nginx/kallithea.access.log;
e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	458 error_log /var/log/nginx/kallithea.error.log;
1745 456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	459
3243 c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	460 ssl on;
4182 05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	461 ssl_certificate your.kallithea.server.crt;
05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	462 ssl_certificate_key your.kallithea.server.key;
3243 c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	463
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	464 ssl_session_timeout 5m;
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	465
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	466 ssl_protocols SSLv3 TLSv1;
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	467 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;
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	468 ssl_prefer_server_ciphers on;
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	469
3850 7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	470 ## uncomment root directive if you want to serve static files by nginx
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	471 ## requires static_files = false in .ini file
5880 61954577a0df docs: mention use of static_files, it's setup and implications Mads Kiilerich <madski@unity3d.com> parents: 5855 diff changeset	472 #root /srv/kallithea/kallithea/kallithea/public;
3917 35c0c62583cd Moved proxy include of nginx to place where Marcin Kuzminski <marcin@python-works.com> parents: 3852 diff changeset	473 include /etc/nginx/proxy.conf;
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	474 location / {
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	475 try_files $uri @kallithea;
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	476 }
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	477
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	478 location @kallithea {
5496 2b2216e8af36 docs: update example output and example server configs Søren Løvborg <sorenl@unity3d.com> parents: 5435 diff changeset	479 proxy_pass http://127.0.0.1:5000;
1745 456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	480 }
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	481
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	482 }
8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	483
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	484 Here's the proxy.conf. It's tuned so it will not timeout on long
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	485 pushes or large pushes::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	486
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	487 proxy_redirect off;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	488 proxy_set_header Host $host;
4073 2c82dd8ba318 Added two headers into example nginx proxy conf that allows container auth Marcin Kuzminski <marcin@python-works.com> parents: 3960 diff changeset	489 ## needed for container auth
2c82dd8ba318 Added two headers into example nginx proxy conf that allows container auth Marcin Kuzminski <marcin@python-works.com> parents: 3960 diff changeset	490 #proxy_set_header REMOTE_USER $remote_user;
2c82dd8ba318 Added two headers into example nginx proxy conf that allows container auth Marcin Kuzminski <marcin@python-works.com> parents: 3960 diff changeset	491 #proxy_set_header X-Forwarded-User $remote_user;
1745 456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	492 proxy_set_header X-Url-Scheme $scheme;
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	493 proxy_set_header X-Host $http_host;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	494 proxy_set_header X-Real-IP $remote_addr;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	495 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	496 proxy_set_header Proxy-host $proxy_host;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	497 proxy_buffering off;
1420 a2fe0ac8d007 Updated nginx proxy example to work better with large pushes Marcin Kuzminski <marcin@python-works.com> parents: 1408 diff changeset	498 proxy_connect_timeout 7200;
a2fe0ac8d007 Updated nginx proxy example to work better with large pushes Marcin Kuzminski <marcin@python-works.com> parents: 1408 diff changeset	499 proxy_send_timeout 7200;
a2fe0ac8d007 Updated nginx proxy example to work better with large pushes Marcin Kuzminski <marcin@python-works.com> parents: 1408 diff changeset	500 proxy_read_timeout 7200;
a2fe0ac8d007 Updated nginx proxy example to work better with large pushes Marcin Kuzminski <marcin@python-works.com> parents: 1408 diff changeset	501 proxy_buffers 8 32k;
3919 b367b016ee39 Added large_client_header_buffers directive into example nginx Marcin Kuzminski <marcin@python-works.com> parents: 3917 diff changeset	502 client_max_body_size 1024m;
b367b016ee39 Added large_client_header_buffers directive into example nginx Marcin Kuzminski <marcin@python-works.com> parents: 3917 diff changeset	503 client_body_buffer_size 128k;
b367b016ee39 Added large_client_header_buffers directive into example nginx Marcin Kuzminski <marcin@python-works.com> parents: 3917 diff changeset	504 large_client_header_buffers 8 64k;
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	505
7340 2898ea3ff76c docs: move authentication info to separate file Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7337 diff changeset	506 .. _apache_virtual_host_reverse_proxy:
2898ea3ff76c docs: move authentication info to separate file Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7337 diff changeset	507
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	508
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	509 Apache virtual host reverse proxy example
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	510 -----------------------------------------
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	511
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	512 Here is a sample configuration file for Apache using proxy:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	513
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	514 .. code-block:: apache
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	515
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	516 <VirtualHost *:80>
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	517 ServerName kallithea.example.com
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	518
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	519 <Proxy *>
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	520 # For Apache 2.4 and later:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	521 Require all granted
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	522
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	523 # For Apache 2.2 and earlier, instead use:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	524 # Order allow,deny
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	525 # Allow from all
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	526 </Proxy>
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	527
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	528 #important !
6339 8845ece50d51 docs: remove some references to Pylons Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6335 diff changeset	529 #Directive to properly generate url (clone url) for Kallithea
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	530 ProxyPreserveHost On
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	531
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	532 #kallithea instance
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	533 ProxyPass / http://127.0.0.1:5000/
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	534 ProxyPassReverse / http://127.0.0.1:5000/
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	535
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	536 #to enable https use line below
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	537 #SetEnvIf X-Url-Scheme https HTTPS=1
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	538 </VirtualHost>
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	539
68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	540 Additional tutorial
4915 6892b0515af9 docs: replace a dead link to the pylons cookbook Andrew Shadura <andrew@shadura.me> parents: 4914 diff changeset	541 http://pylonsbook.com/en/1.1/deployment.html#using-apache-to-proxy-requests-to-pylons
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	542
7340 2898ea3ff76c docs: move authentication info to separate file Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7337 diff changeset	543 .. _apache_subdirectory:
2898ea3ff76c docs: move authentication info to separate file Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7337 diff changeset	544
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	545
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	546 Apache as subdirectory
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	547 ----------------------
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	548
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	549 Apache subdirectory part:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	550
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	551 .. code-block:: apache
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	552
6789 4d04ac08fff7 docs: fix some sphinx warnings Mads Kiilerich <mads@kiilerich.com> parents: 6732 diff changeset	553 <Location /PREFIX >
4d04ac08fff7 docs: fix some sphinx warnings Mads Kiilerich <mads@kiilerich.com> parents: 6732 diff changeset	554 ProxyPass http://127.0.0.1:5000/PREFIX
4d04ac08fff7 docs: fix some sphinx warnings Mads Kiilerich <mads@kiilerich.com> parents: 6732 diff changeset	555 ProxyPassReverse http://127.0.0.1:5000/PREFIX
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	556 SetEnvIf X-Url-Scheme https HTTPS=1
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	557 </Location>
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	558
1392 00b8fca6886c fixes issue #206 Marcin Kuzminski <marcin@python-works.com> parents: 1386 diff changeset	559 Besides the regular apache setup you will need to add the following line
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	560 into ``[app:main]`` section of your .ini file::
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	561
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	562 filter-with = proxy-prefix
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	563
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	564 Add the following at the end of the .ini file::
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	565
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	566 [filter:proxy-prefix]
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	567 use = egg:PasteDeploy#prefix
6789 4d04ac08fff7 docs: fix some sphinx warnings Mads Kiilerich <mads@kiilerich.com> parents: 6732 diff changeset	568 prefix = /PREFIX
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	569
6789 4d04ac08fff7 docs: fix some sphinx warnings Mads Kiilerich <mads@kiilerich.com> parents: 6732 diff changeset	570 then change ``PREFIX`` into your chosen prefix
1226 f17fdbe86ab9 update docs for setup Marcin Kuzminski <marcin@python-works.com> parents: 1123 diff changeset	571
7340 2898ea3ff76c docs: move authentication info to separate file Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7337 diff changeset	572 .. _apache_mod_wsgi:
1226 f17fdbe86ab9 update docs for setup Marcin Kuzminski <marcin@python-works.com> parents: 1123 diff changeset	573
5433 fbbe80e3322b docs: consistent spacing around headings Mads Kiilerich <madski@unity3d.com> parents: 5426 diff changeset	574
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	575 Apache with mod_wsgi
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	576 --------------------
5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	577
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	578 Alternatively, Kallithea can be set up with Apache under mod_wsgi. For
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	579 that, you'll need to:
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	580
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	581 - Install mod_wsgi. If using a Debian-based distro, you can install
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	582 the package libapache2-mod-wsgi::
1559 a9fef2e6c1ff Syntax correction on the recently changed documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1558 diff changeset	583
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	584 aptitude install libapache2-mod-wsgi
1559 a9fef2e6c1ff Syntax correction on the recently changed documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1558 diff changeset	585
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	586 - Enable mod_wsgi::
1559 a9fef2e6c1ff Syntax correction on the recently changed documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1558 diff changeset	587
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	588 a2enmod wsgi
1559 a9fef2e6c1ff Syntax correction on the recently changed documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1558 diff changeset	589
5789 8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	590 - Add global Apache configuration to tell mod_wsgi that Python only will be
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	591 used in the WSGI processes and shouldn't be initialized in the Apache
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	592 processes::
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	593
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	594 WSGIRestrictEmbedded On
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	595
8610 7a1371d659c5 docs: clarify how to activate virtualenv from mod_wsgi with py3 Mads Kiilerich <mads@kiilerich.com> parents: 8607 diff changeset	596 - Create a WSGI dispatch script, like the one below. The ``WSGIDaemonProcess``
7a1371d659c5 docs: clarify how to activate virtualenv from mod_wsgi with py3 Mads Kiilerich <mads@kiilerich.com> parents: 8607 diff changeset	597 ``python-home`` directive will make sure it uses the right Python Virtual
7a1371d659c5 docs: clarify how to activate virtualenv from mod_wsgi with py3 Mads Kiilerich <mads@kiilerich.com> parents: 8607 diff changeset	598 Environment and that paste thus can pick up the right Kallithea
7a1371d659c5 docs: clarify how to activate virtualenv from mod_wsgi with py3 Mads Kiilerich <mads@kiilerich.com> parents: 8607 diff changeset	599 application.
7651 ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7497 diff changeset	600
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7497 diff changeset	601 .. code-block:: python
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	602
7651 ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7497 diff changeset	603 ini = '/srv/kallithea/my.ini'
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7497 diff changeset	604 from logging.config import fileConfig
8086 488b52cad890 logging: always invoke fileConfig with '__file__' and 'here' Wolfgang Scherer <Wolfgang.Scherer@gmx.de> parents: 7936 diff changeset	605 fileConfig(ini, {'__file__': ini, 'here': '/srv/kallithea'})
7651 ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7497 diff changeset	606 from paste.deploy import loadapp
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7497 diff changeset	607 application = loadapp('config:' + ini)
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	608
7652 759d5143042c docs: tweak documentation of Apache+mod_wsgi further Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7651 diff changeset	609 - Add the necessary ``WSGI*`` directives to the Apache Virtual Host configuration
759d5143042c docs: tweak documentation of Apache+mod_wsgi further Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7651 diff changeset	610 file, like in the example below. Notice that the WSGI dispatch script created
759d5143042c docs: tweak documentation of Apache+mod_wsgi further Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7651 diff changeset	611 above is referred to with the ``WSGIScriptAlias`` directive.
7653 9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340) Mads Kiilerich <mads@kiilerich.com> parents: 7652 diff changeset	612 The default locale settings Apache provides for web services are often not
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340) Mads Kiilerich <mads@kiilerich.com> parents: 7652 diff changeset	613 adequate, with `C` as the default language and `ASCII` as the encoding.
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340) Mads Kiilerich <mads@kiilerich.com> parents: 7652 diff changeset	614 Instead, use the ``lang`` parameter of ``WSGIDaemonProcess`` to specify a
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340) Mads Kiilerich <mads@kiilerich.com> parents: 7652 diff changeset	615 suitable locale. See also the :ref:`overview` section and the
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340) Mads Kiilerich <mads@kiilerich.com> parents: 7652 diff changeset	616 `WSGIDaemonProcess documentation`_.
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340) Mads Kiilerich <mads@kiilerich.com> parents: 7652 diff changeset	617
7652 759d5143042c docs: tweak documentation of Apache+mod_wsgi further Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7651 diff changeset	618 Apache will by default run as a special Apache user, on Linux systems
759d5143042c docs: tweak documentation of Apache+mod_wsgi further Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7651 diff changeset	619 usually ``www-data`` or ``apache``. If you need to have the repositories
759d5143042c docs: tweak documentation of Apache+mod_wsgi further Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7651 diff changeset	620 directory owned by a different user, use the user and group options to
759d5143042c docs: tweak documentation of Apache+mod_wsgi further Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7651 diff changeset	621 WSGIDaemonProcess to set the name of the user and group.
759d5143042c docs: tweak documentation of Apache+mod_wsgi further Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7651 diff changeset	622
759d5143042c docs: tweak documentation of Apache+mod_wsgi further Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7651 diff changeset	623 Once again, check that all paths are correctly specified.
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	624
7651 ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7497 diff changeset	625 .. code-block:: apache
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	626
7651 ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7497 diff changeset	627 WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100 \
7653 9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340) Mads Kiilerich <mads@kiilerich.com> parents: 7652 diff changeset	628 python-home=/srv/kallithea/venv lang=C.UTF-8
7651 ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7497 diff changeset	629 WSGIProcessGroup kallithea
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7497 diff changeset	630 WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
ee37a78c6950 docs: move Apache+mod_wsgi example code to the corresponding bullets Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7497 diff changeset	631 WSGIPassAuthorization On
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	632
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	633
591 1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	634 Other configuration files
1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	635 -------------------------
1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	636
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	637 A number of `example init.d scripts`__ can be found in
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	638 the ``init.d`` directory of the Kallithea source.
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	639
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	640 .. __: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ .
591 1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	641
5433 fbbe80e3322b docs: consistent spacing around headings Mads Kiilerich <madski@unity3d.com> parents: 5426 diff changeset	642
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	643 .. _python: http://www.python.org/
7230 d24051ce961c issues: support generic regex replacements in issue_url and issue_prefix Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> parents: 7099 diff changeset	644 .. _Python regular expression documentation: https://docs.python.org/2/library/re.html
6334 cc21a2b86a30 docs: update links to Mercurial's website and wiki Anton Shestakov <av6@dwimlabs.net> parents: 5791 diff changeset	645 .. _Mercurial: https://www.mercurial-scm.org/
4925 56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	646 .. _Celery: http://celeryproject.org/
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	647 .. _Celery documentation: http://docs.celeryproject.org/en/latest/getting-started/index.html
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	648 .. _RabbitMQ: http://www.rabbitmq.com/
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	649 .. _Redis: http://redis.io/
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	650 .. _mercurial-server: http://www.lshift.net/mercurial-server.html
6334 cc21a2b86a30 docs: update links to Mercurial's website and wiki Anton Shestakov <av6@dwimlabs.net> parents: 5791 diff changeset	651 .. _PublishingRepositories: https://www.mercurial-scm.org/wiki/PublishingRepositories
7653 9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340) Mads Kiilerich <mads@kiilerich.com> parents: 7652 diff changeset	652 .. _WSGIDaemonProcess documentation: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIDaemonProcess.html

Mercurial > kallithea

annotate docs/setup.rst @ 8612:4d742b172010