kallithea: docs/setup.rst annotate

annotate docs/setup.rst @ 7099:1969f7dfb6b0

move package.json to root directory In the future we'll probably use it to manage more then just less/css stuff. So the less directory is the wrong place. The most common place is the root directory, so lets put it there. Also, this way the --prefix parameter for npm is no longer required.

author	domruf <dominikruf@gmail.com>
date	Mon, 18 Dec 2017 22:20:10 +0100
parents	6ef837acb0d2
children	d24051ce961c

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
7055 6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	8 Preparing front-end
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	9 -------------------
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	10
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	11 Temporarily, in the current Kallithea version, some extra steps are required to
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	12 build front-end files:
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	13
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	14 Find the right ``kallithea/public/less`` path with::
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	15
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	16 python -c "import os, kallithea; print os.path.join(os.path.dirname(os.path.abspath(kallithea.__file__)), 'public', 'less')"
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	17
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	18 Then run::
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	19
7099 1969f7dfb6b0 move package.json to root directory domruf <dominikruf@gmail.com> parents: 7055 diff changeset	20 npm install
1969f7dfb6b0 move package.json to root directory domruf <dominikruf@gmail.com> parents: 7055 diff changeset	21 npm run less
7055 6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	22
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea domruf <dominikruf@gmail.com> parents: 6898 diff changeset	23
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	24 Setting up Kallithea
1448 b05eb16ea105 fixes #206 Marcin Kuzminski <marcin@python-works.com> parents: 1420 diff changeset	25 --------------------
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	26
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	27 First, you will need to create a Kallithea configuration file. Run the
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	28 following command to do so::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	29
6555 213085032127 gearbox: make a make-config sub-command available again Mads Kiilerich <madski@unity3d.com> parents: 6554 diff changeset	30 gearbox make-config my.ini
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	31
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	32 This will create the file ``my.ini`` in the current directory. This
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	33 configuration file contains the various settings for Kallithea, e.g.
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	34 proxy port, email settings, usage of static files, cache, Celery
6898 a8b9f2d68e7d make-config: allow configuration of any ini value Mads Kiilerich <mads@kiilerich.com> parents: 6789 diff changeset	35 settings, and logging. Extra settings can be specified like::
a8b9f2d68e7d make-config: allow configuration of any ini value Mads Kiilerich <mads@kiilerich.com> parents: 6789 diff changeset	36
a8b9f2d68e7d make-config: allow configuration of any ini value Mads Kiilerich <mads@kiilerich.com> parents: 6789 diff changeset	37 gearbox make-config 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	38
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	39 Next, you need to create the databases used by Kallithea. It is recommended to
4914 95fe05b1e5f8 docs: better capitalisation Andrew Shadura <andrew@shadura.me> parents: 4902 diff changeset	40 use PostgreSQL or SQLite (default). If you choose a database other than the
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	41 default, ensure you properly adjust the database URL in your ``my.ini``
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	42 configuration file to use this other database. Kallithea currently supports
4914 95fe05b1e5f8 docs: better capitalisation Andrew Shadura <andrew@shadura.me> parents: 4902 diff changeset	43 PostgreSQL, SQLite and MySQL databases. Create the database by running
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	44 the following command::
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	45
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	46 gearbox setup-db -c my.ini
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	47
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	48 This will prompt you for a "root" path. This "root" path is the location where
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	49 Kallithea will store all of its repositories on the current machine. After
4185 aaa7c3331186 Rename paster command setup-rhodecode to setup-db Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4182 diff changeset	50 entering this "root" path ``setup-db`` will also prompt you for a username
aaa7c3331186 Rename paster command setup-rhodecode to setup-db Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4182 diff changeset	51 and password for the initial admin account which ``setup-db`` sets
2284 e285aa097a81 new setup-rhodecode command with optional defaults Marcin Kuzminski <marcin@python-works.com> parents: 2105 diff changeset	52 up for you.
845 a040597b070b docs update Marcin Kuzminski <marcin@python-works.com> parents: 777 diff changeset	53
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	54 The ``setup-db`` values can also be given on the command line.
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	55 Example::
2358 69df04ee1e2b added detailed step-by-step installation instruction for windows Marcin Kuzminski <marcin@python-works.com> parents: 2284 diff changeset	56
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	57 gearbox setup-db -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	58
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	59 The ``setup-db`` 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	60 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	61 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	62 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	63 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	64 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	65 path to the root).
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	66
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	67 .. note:: the given path for Mercurial_ repositories must be write
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	68 accessible for the application. It's very important since
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	69 the Kallithea web interface will work without write access,
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	70 but when trying to do a push it will fail with permission
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	71 denied errors unless it has write access.
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	72
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	73 You are now ready to use Kallithea. To run it simply execute::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	74
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	75 gearbox serve -c my.ini
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	76
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	77 - 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	78 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	79 configuration file created in the previous step.
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	80 - Log in to Kallithea using the admin account created when running ``setup-db``.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	81 - 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	82 Remember to update these if needed.
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	83 - 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	84 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	85 repositories.
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	86
5077 faf943716616 rcextensions: cleanup of code and documentation Mads Kiilerich <madski@unity3d.com> parents: 4955 diff changeset	87
6695 8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	88 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	89 -----------------------------------
6732 793ea7823938 docs/setup: heading whitespace cleanup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6695 diff changeset	90
6695 8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	91 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	92 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	93 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	94 (because the translation file for that language does not yet exist or is
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	95 incomplete), the language specified in setting ``i18n.lang`` in the Kallithea
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	96 configuration file is used as fallback. If no fallback language is explicitly
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	97 specified, English is used.
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	98
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	99 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	100 fixed language regardless of user preference, set ``i18n.enabled = false`` and
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	101 set ``i18n.lang`` to the desired language (or leave empty for English).
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	102
8931078f70db docs: add documentation about internationalization from a user perspective Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	103
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	104 Using Kallithea with SSH
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	105 ------------------------
8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	106
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	107 Kallithea currently only hosts repositories using http and https. (The addition
1309 61a6a7bf2cbd small docs updates Marcin Kuzminski <marcin@python-works.com> parents: 1292 diff changeset	108 of ssh hosting is a planned future feature.) However you can easily use ssh in
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	109 parallel with Kallithea. (Repository access via ssh is a standard "out of
4914 95fe05b1e5f8 docs: better capitalisation Andrew Shadura <andrew@shadura.me> parents: 4902 diff changeset	110 the box" feature of Mercurial_ and you can use this to access any of the
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	111 repositories that Kallithea is hosting. See PublishingRepositories_)
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	112
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	113 Kallithea repository structures are kept in directories with the same name
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	114 as the project. When using repository groups, each group is a subdirectory.
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	115 This allows you to easily use ssh for accessing repositories.
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	116
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	117 In order to use ssh you need to make sure that your web server and the users'
1309 61a6a7bf2cbd small docs updates Marcin Kuzminski <marcin@python-works.com> parents: 1292 diff changeset	118 login accounts have the correct permissions set on the appropriate directories.
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	119
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	120 .. note:: These permissions are independent of any permissions you
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	121 have set up using the Kallithea web interface.
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	122
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	123 If your main directory (the same as set in Kallithea settings) is for
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	124 example set to ``/srv/repos`` and the repository you are using is
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	125 named ``kallithea``, then to clone via ssh you should run::
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	126
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	127 hg clone ssh://user@kallithea.example.com/srv/repos/kallithea
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	128
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	129 Using other external tools such as mercurial-server_ or using ssh key-based
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	130 authentication is fully supported.
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	131
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	132 .. note:: In an advanced setup, in order for your ssh access to use
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	133 the same permissions as set up via the Kallithea web
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	134 interface, you can create an authentication hook to connect
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	135 to the Kallithea db and run check functions for permissions
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	136 against that.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	137
5433 fbbe80e3322b docs: consistent spacing around headings Mads Kiilerich <madski@unity3d.com> parents: 5426 diff changeset	138
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	139 Setting up Whoosh full text search
341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	140 ----------------------------------
341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	141
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	142 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	143
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	144 .. __: https://pythonhosted.org/Whoosh/
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	145
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	146 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	147
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	148 gearbox make-index -c my.ini
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	149
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	150 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	151
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	152 gearbox make-index -c my.ini -f
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	153
5855 1048307eb1f5 spelling: overridden timeless@gmail.com parents: 5832 diff changeset	154 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	155 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	156
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	157 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	158
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	159 gearbox make-index -c my.ini --index-only=vcs,kallithea
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	160
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	161 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	162 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	163
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	164 0 3 * * * /path/to/virtualenv/bin/gearbox make-index -c /path/to/kallithea/my.ini
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	165
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	166 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	167 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	168 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	169 from index.
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	170
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	171 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	172 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	173
5788 2d89d49c30e8 docs: add notes about IIS, Windows Authentication and Mercurial Konstantin Veretennicov <kveretennicov@gmail.com> parents: 5592 diff changeset	174 .. _ldap-setup:
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	175
5815 6feed82b76a3 Merge stable Mads Kiilerich <madski@unity3d.com> parents: 5792 diff changeset	176
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	177 Setting up LDAP support
1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	178 -----------------------
1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	179
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	180 Kallithea supports LDAP authentication. In order
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	181 to use LDAP, you have to install the python-ldap_ package. This package is
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	182 available via PyPI, so you can install it by running::
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	183
1123 9472a0150bf0 docs update Marcin Kuzminski <marcin@python-works.com> parents: 1092 diff changeset	184 pip install python-ldap
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	185
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	186 .. note:: ``python-ldap`` requires some libraries to be installed on
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	187 your system, so before installing it check that you have at
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	188 least the ``openldap`` and ``sasl`` libraries.
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	189
5426 66f1b9745905 docs: update menu navigation notation to use Menu > Menu Item Søren Løvborg <sorenl@unity3d.com> parents: 5425 diff changeset	190 Choose Admin > Authentication, click the ``kallithea.lib.auth_modules.auth_ldap`` button
66f1b9745905 docs: update menu navigation notation to use Menu > Menu Item Søren Løvborg <sorenl@unity3d.com> parents: 5425 diff changeset	191 and then Save, to enable the LDAP plugin and configure its settings.
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	192
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	193 Here's a typical LDAP setup::
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	194
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	195 Connection settings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	196 Enable LDAP = checked
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	197 Host = host.example.com
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	198 Account = <account>
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	199 Password = <password>
6457 d0f6bd6190c8 auth: change default LDAP to LDAPS on port 636 - insecure authentication is kind of pointless Mads Kiilerich <madski@unity3d.com> parents: 6339 diff changeset	200 Connection Security = LDAPS
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	201 Certificate Checks = DEMAND
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	202
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	203 Search settings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	204 Base DN = CN=users,DC=host,DC=example,DC=org
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	205 LDAP Filter = (&(objectClass=user)(!(objectClass=computer)))
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	206 LDAP Search Scope = SUBTREE
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	207
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	208 Attribute mappings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	209 Login Attribute = uid
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	210 First Name Attribute = firstName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	211 Last Name Attribute = lastName
5412 2079e864ce51 spelling: use "email" consistently Søren Løvborg <sorenl@unity3d.com> parents: 5077 diff changeset	212 Email Attribute = mail
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	213
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	214 If your user groups are placed in an Organisation Unit (OU) structure, the Search Settings configuration differs::
3801 6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units. Magnus Ericmats <magnus.ericmats@gmail.com> parents: 3622 diff changeset	215
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units. Magnus Ericmats <magnus.ericmats@gmail.com> parents: 3622 diff changeset	216 Search settings
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units. Magnus Ericmats <magnus.ericmats@gmail.com> parents: 3622 diff changeset	217 Base DN = DC=host,DC=example,DC=org
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units. Magnus Ericmats <magnus.ericmats@gmail.com> parents: 3622 diff changeset	218 LDAP Filter = (&(memberOf=CN=your user group,OU=subunit,OU=unit,DC=host,DC=example,DC=org)(objectClass=user))
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units. Magnus Ericmats <magnus.ericmats@gmail.com> parents: 3622 diff changeset	219 LDAP Search Scope = SUBTREE
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units. Magnus Ericmats <magnus.ericmats@gmail.com> parents: 3622 diff changeset	220
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	221 .. _enable_ldap:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	222
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	223 Enable LDAP : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	224 Whether to use LDAP for authenticating users.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	225
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	226 .. _ldap_host:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	227
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	228 Host : required
2916 f6685a62e455 Updated docs about LDAP failover server list option Marcin Kuzminski <marcin@python-works.com> parents: 2906 diff changeset	229 LDAP server hostname or IP address. Can be also a comma separated
f6685a62e455 Updated docs about LDAP failover server list option Marcin Kuzminski <marcin@python-works.com> parents: 2906 diff changeset	230 list of servers to support LDAP fail-over.
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	231
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	232 .. _Port:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	233
6331 949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	234 Port : optional
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	235 Defaults to 389 for PLAIN un-encrypted LDAP and START_TLS.
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	236 Defaults to 636 for LDAPS.
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	237
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	238 .. _ldap_account:
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	239
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	240 Account : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	241 Only required if the LDAP server does not allow anonymous browsing of
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	242 records. This should be a special account for record browsing. This
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	243 will require `LDAP Password`_ below.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	244
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	245 .. _LDAP Password:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	246
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	247 Password : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	248 Only required if the LDAP server does not allow anonymous browsing of
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	249 records.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	250
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	251 .. _Enable LDAPS:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	252
1292 c0335c1dee36 added some fixes to LDAP form re-submition, new simples ldap-settings getter. Marcin Kuzminski <marcin@python-works.com> parents: 1284 diff changeset	253 Connection Security : required
c0335c1dee36 added some fixes to LDAP form re-submition, new simples ldap-settings getter. Marcin Kuzminski <marcin@python-works.com> parents: 1284 diff changeset	254 Defines the connection to LDAP server
c0335c1dee36 added some fixes to LDAP form re-submition, new simples ldap-settings getter. Marcin Kuzminski <marcin@python-works.com> parents: 1284 diff changeset	255
6331 949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	256 PLAIN
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	257 Plain unencrypted LDAP connection.
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	258 This will by default use `Port`_ 389.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	259
6331 949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	260 LDAPS
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	261 Use secure LDAPS connections according to `Certificate
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	262 Checks`_ configuration.
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	263 This will by default use `Port`_ 636.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	264
6331 949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	265 START_TLS
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	266 Use START TLS according to `Certificate Checks`_ configuration on an
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	267 apparently "plain" LDAP connection.
949c843bb535 auth: refactor ldap parameter handling - make it clear that port is optional Mads Kiilerich <madski@unity3d.com> parents: 6330 diff changeset	268 This will by default use `Port`_ 389.
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	269
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	270 .. _Certificate Checks:
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	271
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	272 Certificate Checks : optional
5435 60e04a21bf0f docs: more consistent use of -- Mads Kiilerich <madski@unity3d.com> parents: 5434 diff changeset	273 How SSL certificates verification is handled -- this is only useful when
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	274 `Enable LDAPS`_ is enabled. Only DEMAND or HARD offer full SSL security
6330 7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	275 with mandatory certificate validation, while the other options are
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	276 susceptible to man-in-the-middle attacks.
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	277
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	278 NEVER
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	279 A serve certificate will never be requested or checked.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	280
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	281 ALLOW
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	282 A server certificate is requested. Failure to provide a
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	283 certificate or providing a bad certificate will not terminate the
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	284 session.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	285
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	286 TRY
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	287 A server certificate is requested. Failure to provide a
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	288 certificate does not halt the session; providing a bad certificate
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	289 halts the session.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	290
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	291 DEMAND
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	292 A server certificate is requested and must be provided and
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	293 authenticated for the session to proceed.
775 aaf2fc59a39a fixes #77 and adds extendable base Dn with custom uid specification Marcin Kuzminski <marcin@python-works.com> parents: 770 diff changeset	294
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	295 HARD
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	296 The same as DEMAND.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	297
6330 7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	298 .. _Custom CA Certificates:
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	299
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	300 Custom CA Certificates : optional
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	301 Directory used by OpenSSL to find CAs for validating the LDAP server certificate.
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	302 Python 2.7.10 and later default to using the system certificate store, and
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	303 this should thus not be necessary when using certificates signed by a CA
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	304 trusted by the system.
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	305 It can be set to something like `/etc/openldap/cacerts` on older systems or
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	306 if using self-signed certificates.
7ce3897bacd0 auth: make ldap OPT_X_TLS_CACERTDIR configurable Mads Kiilerich <madski@unity3d.com> parents: 6153 diff changeset	307
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	308 .. _Base DN:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	309
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	310 Base DN : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	311 The Distinguished Name (DN) where searches for users will be performed.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	312 Searches can be controlled by `LDAP Filter`_ and `LDAP Search Scope`_.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	313
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	314 .. _LDAP Filter:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	315
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	316 LDAP Filter : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	317 A LDAP filter defined by RFC 2254. This is more useful when `LDAP
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	318 Search Scope`_ is set to SUBTREE. The filter is useful for limiting
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	319 which LDAP objects are identified as representing Users for
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	320 authentication. The filter is augmented by `Login Attribute`_ below.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	321 This can commonly be left blank.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	322
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	323 .. _LDAP Search Scope:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	324
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	325 LDAP Search Scope : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	326 This limits how far LDAP will search for a matching object.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	327
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	328 BASE
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	329 Only allows searching of `Base DN`_ and is usually not what you
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	330 want.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	331
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	332 ONELEVEL
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	333 Searches all entries under `Base DN`_, but not Base DN itself.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	334
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	335 SUBTREE
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	336 Searches all entries below `Base DN`_, but not Base DN itself.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	337 When using SUBTREE `LDAP Filter`_ is useful to limit object
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	338 location.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	339
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	340 .. _Login Attribute:
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	341
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	342 Login Attribute : required
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	343 The LDAP record attribute that will be matched as the USERNAME or
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	344 ACCOUNT used to connect to Kallithea. This will be added to `LDAP
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	345 Filter`_ for locating the User object. If `LDAP Filter`_ is specified as
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	346 "LDAPFILTER", `Login Attribute`_ is specified as "uid" and the user has
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	347 connected as "jsmith" then the `LDAP Filter`_ will be augmented as below
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	348 ::
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	349
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	350 (&(LDAPFILTER)(uid=jsmith))
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	351
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	352 .. _ldap_attr_firstname:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	353
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	354 First Name Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	355 The LDAP record attribute which represents the user's first name.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	356
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	357 .. _ldap_attr_lastname:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	358
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	359 Last Name Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	360 The LDAP record attribute which represents the user's last name.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	361
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	362 .. _ldap_attr_email:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	363
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	364 Email Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	365 The LDAP record attribute which represents the user's email address.
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	366
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	367 If all data are entered correctly, and python-ldap_ is properly installed
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	368 users should be granted access to Kallithea with LDAP accounts. At this
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	369 time user information is copied from LDAP into the Kallithea user database.
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	370 This means that updates of an LDAP user object may not be reflected as a
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	371 user update in Kallithea.
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	372
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	373 If You have problems with LDAP access and believe You entered correct
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	374 information check out the Kallithea logs, any error messages sent from LDAP
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	375 will be saved there.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	376
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	377 Active Directory
5575 ed2fb6e84a02 docs: use consistent style for section titles Mads Kiilerich <madski@unity3d.com> parents: 5534 diff changeset	378 ^^^^^^^^^^^^^^^^
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	379
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	380 Kallithea can use Microsoft Active Directory for user authentication. This
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	381 is done through an LDAP or LDAPS connection to Active Directory. The
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	382 following LDAP configuration settings are typical for using Active
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	383 Directory ::
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	384
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	385 Base DN = OU=SBSUsers,OU=Users,OU=MyBusiness,DC=v3sys,DC=local
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	386 Login Attribute = sAMAccountName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	387 First Name Attribute = givenName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	388 Last Name Attribute = sn
5412 2079e864ce51 spelling: use "email" consistently Søren Løvborg <sorenl@unity3d.com> parents: 5077 diff changeset	389 Email Attribute = mail
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	390
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	391 All other LDAP settings will likely be site-specific and should be
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	392 appropriately configured.
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	393
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	394
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	395 Authentication by container or reverse-proxy
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	396 --------------------------------------------
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	397
4501 a68fc4abeda3 issue #7 remove obsolete configuration domruf <dominikruf@gmail.com> parents: 4448 diff changeset	398 Kallithea supports delegating the authentication
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	399 of users to its WSGI container, or to a reverse-proxy server through which all
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	400 clients access the application.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	401
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	402 When these authentication methods are enabled in Kallithea, it uses the
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	403 username that the container/proxy (Apache or Nginx, etc.) provides and doesn't
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	404 perform the authentication itself. The authorization, however, is still done by
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	405 Kallithea according to its settings.
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	406
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	407 When a user logs in for the first time using these authentication methods,
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	408 a matching user account is created in Kallithea with default permissions. An
e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	409 administrator can then modify it using Kallithea's admin interface.
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	410
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	411 It's also possible for an administrator to create accounts and configure their
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	412 permissions before the user logs in for the first time, using the :ref:`create-user` API.
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	413
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	414 Container-based authentication
5575 ed2fb6e84a02 docs: use consistent style for section titles Mads Kiilerich <madski@unity3d.com> parents: 5534 diff changeset	415 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	416
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	417 In a container-based authentication setup, Kallithea reads the user name from
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	418 the ``REMOTE_USER`` server variable provided by the WSGI container.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	419
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	420 After setting up your container (see `Apache with mod_wsgi`_), you'll need
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	421 to configure it to require authentication on the location configured for
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	422 Kallithea.
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	423
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	424 Proxy pass-through authentication
5575 ed2fb6e84a02 docs: use consistent style for section titles Mads Kiilerich <madski@unity3d.com> parents: 5534 diff changeset	425 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	426
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	427 In a proxy pass-through authentication setup, Kallithea reads the user name
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	428 from the ``X-Forwarded-User`` request header, which should be configured to be
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	429 sent by the reverse-proxy server.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	430
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	431 After setting up your proxy solution (see `Apache virtual host reverse proxy example`_,
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	432 `Apache as subdirectory`_ or `Nginx virtual host example`_), you'll need to
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	433 configure the authentication and add the username in a request header named
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	434 ``X-Forwarded-User``.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	435
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	436 For example, the following config section for Apache sets a subdirectory in a
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	437 reverse-proxy setup with basic auth:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	438
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	439 .. code-block:: apache
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	440
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	441 <Location /someprefix>
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	442 ProxyPass http://127.0.0.1:5000/someprefix
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	443 ProxyPassReverse http://127.0.0.1:5000/someprefix
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	444 SetEnvIf X-Url-Scheme https HTTPS=1
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	445
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	446 AuthType Basic
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	447 AuthName "Kallithea authentication"
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	448 AuthUserFile /srv/kallithea/.htpasswd
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	449 Require valid-user
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	450
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	451 RequestHeader unset X-Forwarded-User
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	452
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	453 RewriteEngine On
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	454 RewriteCond %{LA-U:REMOTE_USER} (.+)
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	455 RewriteRule .* - [E=RU:%1]
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	456 RequestHeader set X-Forwarded-User %{RU}e
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	457 </Location>
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	458
5609 ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	459 Setting metadata in container/reverse-proxy
5815 6feed82b76a3 Merge stable Mads Kiilerich <madski@unity3d.com> parents: 5792 diff changeset	460 """""""""""""""""""""""""""""""""""""""""""
5609 ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	461 When a new user account is created on the first login, Kallithea has no information about
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	462 the user's email and full name. So you can set some additional request headers like in the
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	463 example below. In this example the user is authenticated via Kerberos and an Apache
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	464 mod_python fixup handler is used to get the user information from a LDAP server. But you
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	465 could set the request headers however you want.
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	466
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	467 .. code-block:: apache
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	468
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	469 <Location /someprefix>
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	470 ProxyPass http://127.0.0.1:5000/someprefix
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	471 ProxyPassReverse http://127.0.0.1:5000/someprefix
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	472 SetEnvIf X-Url-Scheme https HTTPS=1
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	473
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	474 AuthName "Kerberos Login"
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	475 AuthType Kerberos
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	476 Krb5Keytab /etc/apache2/http.keytab
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	477 KrbMethodK5Passwd off
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	478 KrbVerifyKDC on
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	479 Require valid-user
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	480
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	481 PythonFixupHandler ldapmetadata
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	482
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	483 RequestHeader set X_REMOTE_USER %{X_REMOTE_USER}e
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	484 RequestHeader set X_REMOTE_EMAIL %{X_REMOTE_EMAIL}e
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	485 RequestHeader set X_REMOTE_FIRSTNAME %{X_REMOTE_FIRSTNAME}e
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	486 RequestHeader set X_REMOTE_LASTNAME %{X_REMOTE_LASTNAME}e
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	487 </Location>
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	488
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	489 .. code-block:: python
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	490
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	491 from mod_python import apache
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	492 import ldap
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	493
6457 d0f6bd6190c8 auth: change default LDAP to LDAPS on port 636 - insecure authentication is kind of pointless Mads Kiilerich <madski@unity3d.com> parents: 6339 diff changeset	494 LDAP_SERVER = "ldaps://server.mydomain.com:636"
5609 ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	495 LDAP_USER = ""
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	496 LDAP_PASS = ""
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	497 LDAP_ROOT = "dc=mydomain,dc=com"
5817 c37e5e57b17a spelling: account timeless@gmail.com parents: 5815 diff changeset	498 LDAP_FILTER = "sAMAccountName=%s"
c37e5e57b17a spelling: account timeless@gmail.com parents: 5815 diff changeset	499 LDAP_ATTR_LIST = ['sAMAccountName','givenname','sn','mail']
5609 ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	500
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	501 def fixuphandler(req):
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	502 if req.user is None:
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	503 # no user to search for
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	504 return apache.OK
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	505 else:
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	506 try:
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	507 if('\\' in req.user):
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	508 username = req.user.split('\\')[1]
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	509 elif('@' in req.user):
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	510 username = req.user.split('@')[0]
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	511 else:
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	512 username = req.user
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	513 l = ldap.initialize(LDAP_SERVER)
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	514 l.simple_bind_s(LDAP_USER, LDAP_PASS)
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	515 r = l.search_s(LDAP_ROOT, ldap.SCOPE_SUBTREE, LDAP_FILTER % username, attrlist=LDAP_ATTR_LIST)
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	516
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	517 req.subprocess_env['X_REMOTE_USER'] = username
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	518 req.subprocess_env['X_REMOTE_EMAIL'] = r[0][1]['mail'][0].lower()
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	519 req.subprocess_env['X_REMOTE_FIRSTNAME'] = "%s" % r[0][1]['givenname'][0]
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	520 req.subprocess_env['X_REMOTE_LASTNAME'] = "%s" % r[0][1]['sn'][0]
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	521 except Exception, e:
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	522 apache.log_error("error getting data from ldap %s" % str(e), apache.APLOG_ERR)
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	523
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	524 return apache.OK
ada6571a6d27 auth: let container authentication get email, first and last name from custom headers domruf <dominikruf@gmail.com> parents: 5594 diff changeset	525
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	526 .. note::
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	527 If you enable proxy pass-through authentication, make sure your server is
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	528 only accessible through the proxy. Otherwise, any client would be able to
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	529 forge the authentication header and could effectively become authenticated
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	530 using any account of their liking.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	531
5413 22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings Mads Kiilerich <madski@unity3d.com> parents: 5412 diff changeset	532
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings Mads Kiilerich <madski@unity3d.com> parents: 5412 diff changeset	533 Integration with issue trackers
1838 2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	534 -------------------------------
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	535
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	536 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	537 to define a regular expression that will match an issue ID in commit messages,
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	538 and have that replaced with a URL to the issue. To enable this simply
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	539 uncomment the following variables in the ini file::
1838 2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	540
3943 a5bccf34c512 fixed docs error, should be issue_pat Marcin Kuzminski <marcin@python-works.com> parents: 3923 diff changeset	541 issue_pat = (?:^#\|\s#)(\w+)
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	542 issue_server_link = https://issues.example.com/{repo}/issue/{id}
1838 2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	543 issue_prefix = #
2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	544
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	545 ``issue_pat`` is the regular expression describing which strings in
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	546 commit messages will be treated as issue references. A match group in
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	547 parentheses should be used to specify the actual issue id.
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	548
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	549 The default expression matches issues in the format ``#<number>``, e.g., ``#300``.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	550
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	551 Matched issue references are replaced with the link specified in
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	552 ``issue_server_link``. ``{id}`` is replaced with the issue ID, and
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	553 ``{repo}`` with the repository name. Since the # is stripped away,
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	554 ``issue_prefix`` is prepended to the link text. ``issue_prefix`` doesn't
4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	555 necessarily need to be ``#``: if you set issue prefix to ``ISSUE-`` this will
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	556 generate a URL in the format:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	557
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	558 .. code-block:: html
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	559
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	560 <a href="https://issues.example.com/example_repo/issue/300">ISSUE-300</a>
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	561
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	562 If needed, more than one pattern can be specified by appending a unique suffix to
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	563 the variables. For example::
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	564
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	565 issue_pat_wiki = (?:wiki-)(.+)
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	566 issue_server_link_wiki = https://wiki.example.com/{id}
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	567 issue_prefix_wiki = WIKI-
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	568
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	569 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	570 such reference will be transformed into:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	571
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	572 .. code-block:: html
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	573
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	574 <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	575
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	576
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	577 Hook management
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	578 ---------------
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	579
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	580 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	581 To manage hooks, choose Admin > Settings > Hooks.
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	582
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	583 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	584
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	585 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	586 ``<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	587 can be found in ``kallithea.lib.hooks``.
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	588
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	589
2017 03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	590 Changing default encoding
03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	591 -------------------------
03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	592
4914 95fe05b1e5f8 docs: better capitalisation Andrew Shadura <andrew@shadura.me> parents: 4902 diff changeset	593 By default, Kallithea uses UTF-8 encoding.
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	594 This is configurable as ``default_encoding`` in the .ini file.
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	595 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	596 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	597 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	598 when there are encode/decode errors.
03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	599
03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	600
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	601 Celery configuration
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	602 --------------------
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	603
4925 56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	604 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	605 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	606
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	607 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	608 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	609 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	610 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	611
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	612 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	613 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	614 or Redis_.
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	615
4925 56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	616 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	617 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	618
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	619 use_celery = true
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	620
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	621 and add or change the ``celery.`` and ``broker.`` configuration variables.
4925 56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	622
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	623 Remember that the ini files use the format with '.' and not with '_' like
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	624 Celery. So for example setting `BROKER_HOST` in Celery means setting
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	625 `broker.host` in the configuration file.
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	626
56cd202b777e docs: move all instructions on Celery to Setup Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4915 diff changeset	627 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	628
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	629 gearbox celeryd -c <configfile.ini>
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack Mads Kiilerich <madski@unity3d.com> parents: 6457 diff changeset	630
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack Mads Kiilerich <madski@unity3d.com> parents: 6457 diff changeset	631 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	632 for more info.
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	633
871 7f9e006aa26f docs update for celeryd Marcin Kuzminski <marcin@python-works.com> parents: 845 diff changeset	634 .. note::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	635 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	636 user that Kallithea runs.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	637
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	638
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	639 HTTPS support
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	640 -------------
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	641
4448 8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	642 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	643
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	644 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	645 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	646
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	647 - 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	648 ``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	649 (default ``http``).
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	650 - 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	651 - 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	652
871 7f9e006aa26f docs update for celeryd Marcin Kuzminski <marcin@python-works.com> parents: 845 diff changeset	653
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	654 Nginx virtual host example
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	655 --------------------------
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	656
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	657 Sample config for Nginx using proxy:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	658
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	659 .. code-block:: nginx
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	660
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	661 upstream kallithea {
1745 456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	662 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	663 # 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	664 #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	665 #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	666 }
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	667
3850 7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	668 ## gist alias
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	669 server {
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	670 listen 443;
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	671 server_name gist.example.com;
3850 7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	672 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	673 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	674
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	675 ssl on;
4182 05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	676 ssl_certificate gist.your.kallithea.server.crt;
05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	677 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	678
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	679 ssl_session_timeout 5m;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	680
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	681 ssl_protocols SSLv3 TLSv1;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	682 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	683 ssl_prefer_server_ciphers on;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	684
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	685 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	686 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	687 }
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	688
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	689 server {
3243 c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	690 listen 443;
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	691 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	692 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	693 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	694
3243 c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	695 ssl on;
4182 05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	696 ssl_certificate your.kallithea.server.crt;
05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	697 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	698
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	699 ssl_session_timeout 5m;
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	700
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	701 ssl_protocols SSLv3 TLSv1;
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	702 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	703 ssl_prefer_server_ciphers on;
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	704
3850 7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	705 ## 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	706 ## 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	707 #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	708 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	709 location / {
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	710 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	711 }
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	712
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	713 location @kallithea {
5496 2b2216e8af36 docs: update example output and example server configs Søren Løvborg <sorenl@unity3d.com> parents: 5435 diff changeset	714 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	715 }
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	716
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	717 }
8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	718
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	719 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	720 pushes or large pushes::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	721
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	722 proxy_redirect off;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	723 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	724 ## 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	725 #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	726 #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	727 proxy_set_header X-Url-Scheme $scheme;
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	728 proxy_set_header X-Host $http_host;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	729 proxy_set_header X-Real-IP $remote_addr;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	730 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	731 proxy_set_header Proxy-host $proxy_host;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	732 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	733 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	734 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	735 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	736 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	737 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	738 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	739 large_client_header_buffers 8 64k;
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	740
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	741
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	742 Apache virtual host reverse proxy example
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	743 -----------------------------------------
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	744
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	745 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	746
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	747 .. code-block:: apache
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	748
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	749 <VirtualHost *:80>
5497 12b47803189f cleanup: use example.com for tests and examples Søren Løvborg <sorenl@unity3d.com> parents: 5496 diff changeset	750 ServerName kallithea.example.com
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	751
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	752 <Proxy *>
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	753 # For Apache 2.4 and later:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	754 Require all granted
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	755
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	756 # 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	757 # Order allow,deny
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	758 # Allow from all
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	759 </Proxy>
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	760
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	761 #important !
6339 8845ece50d51 docs: remove some references to Pylons Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6335 diff changeset	762 #Directive to properly generate url (clone url) for Kallithea
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	763 ProxyPreserveHost On
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	764
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	765 #kallithea instance
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	766 ProxyPass / http://127.0.0.1:5000/
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	767 ProxyPassReverse / http://127.0.0.1:5000/
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	768
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	769 #to enable https use line below
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	770 #SetEnvIf X-Url-Scheme https HTTPS=1
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	771 </VirtualHost>
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	772
68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	773 Additional tutorial
4915 6892b0515af9 docs: replace a dead link to the pylons cookbook Andrew Shadura <andrew@shadura.me> parents: 4914 diff changeset	774 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	775
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	776
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	777 Apache as subdirectory
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	778 ----------------------
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	779
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	780 Apache subdirectory part:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	781
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	782 .. code-block:: apache
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	783
6789 4d04ac08fff7 docs: fix some sphinx warnings Mads Kiilerich <mads@kiilerich.com> parents: 6732 diff changeset	784 <Location /PREFIX >
4d04ac08fff7 docs: fix some sphinx warnings Mads Kiilerich <mads@kiilerich.com> parents: 6732 diff changeset	785 ProxyPass http://127.0.0.1:5000/PREFIX
4d04ac08fff7 docs: fix some sphinx warnings Mads Kiilerich <mads@kiilerich.com> parents: 6732 diff changeset	786 ProxyPassReverse http://127.0.0.1:5000/PREFIX
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	787 SetEnvIf X-Url-Scheme https HTTPS=1
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	788 </Location>
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	789
1392 00b8fca6886c fixes issue #206 Marcin Kuzminski <marcin@python-works.com> parents: 1386 diff changeset	790 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	791 into ``[app:main]`` section of your .ini file::
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	792
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	793 filter-with = proxy-prefix
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	794
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	795 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	796
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	797 [filter:proxy-prefix]
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	798 use = egg:PasteDeploy#prefix
6789 4d04ac08fff7 docs: fix some sphinx warnings Mads Kiilerich <mads@kiilerich.com> parents: 6732 diff changeset	799 prefix = /PREFIX
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	800
6789 4d04ac08fff7 docs: fix some sphinx warnings Mads Kiilerich <mads@kiilerich.com> parents: 6732 diff changeset	801 then change ``PREFIX`` into your chosen prefix
1226 f17fdbe86ab9 update docs for setup Marcin Kuzminski <marcin@python-works.com> parents: 1123 diff changeset	802
5433 fbbe80e3322b docs: consistent spacing around headings Mads Kiilerich <madski@unity3d.com> parents: 5426 diff changeset	803
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	804 Apache with mod_wsgi
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	805 --------------------
5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	806
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	807 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	808 that, you'll need to:
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	809
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	810 - 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	811 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	812
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	813 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	814
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	815 - Enable mod_wsgi::
1559 a9fef2e6c1ff Syntax correction on the recently changed documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1558 diff changeset	816
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	817 a2enmod wsgi
1559 a9fef2e6c1ff Syntax correction on the recently changed documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1558 diff changeset	818
5789 8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	819 - 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	820 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	821 processes::
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	822
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	823 WSGIRestrictEmbedded On
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	824
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	825 - Create a wsgi dispatch script, like the one below. Make sure you
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	826 check that the paths correctly point to where you installed Kallithea
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	827 and its Python Virtual Environment.
4955 4e6dfdb3fa01 docs: English and consistency corrections Michael V. DePalatis <mike@depalatis.net> parents: 4925 diff changeset	828 - Enable the ``WSGIScriptAlias`` directive for the WSGI dispatch script,
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	829 as in the following example. Once again, check the paths are
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	830 correctly specified.
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	831
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	832 Here is a sample excerpt from an Apache Virtual Host configuration file:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	833
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	834 .. code-block:: apache
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	835
6153 d6942b2b421c config: clarify that we only recommend and support single threaded operation Mads Kiilerich <madski@unity3d.com> parents: 5880 diff changeset	836 WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100 \
5789 8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	837 python-home=/srv/kallithea/venv
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	838 WSGIProcessGroup kallithea
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	839 WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
2076 77d215d6121f docs on apache WSGI update Marcin Kuzminski <marcin@python-works.com> parents: 2017 diff changeset	840 WSGIPassAuthorization On
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	841
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	842 Or if using a dispatcher WSGI script with proper virtualenv activation:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	843
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	844 .. code-block:: apache
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	845
6153 d6942b2b421c config: clarify that we only recommend and support single threaded operation Mads Kiilerich <madski@unity3d.com> parents: 5880 diff changeset	846 WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100
5789 8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	847 WSGIProcessGroup kallithea
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	848 WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	849 WSGIPassAuthorization On
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	850
5789 8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	851 Apache will by default run as a special Apache user, on Linux systems
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	852 usually ``www-data`` or ``apache``. If you need to have the repositories
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	853 directory owned by a different user, use the user and group options to
5791 73493ddc8c9e docs: fix typo Mads Kiilerich <madski@unity3d.com> parents: 5789 diff changeset	854 WSGIDaemonProcess to set the name of the user and group.
2800 6540ee9179da updated apache wsgi example ref #535 Marcin Kuzminski <marcin@python-works.com> parents: 2748 diff changeset	855
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	856 Example WSGI dispatch script:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	857
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	858 .. code-block:: python
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	859
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	860 import os
5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	861 os.environ["HGENCODING"] = "UTF-8"
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	862 os.environ['PYTHON_EGG_CACHE'] = '/srv/kallithea/.egg-cache'
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	863
5832 722677a67afb spelling: current timeless@gmail.com parents: 5817 diff changeset	864 # sometimes it's needed to set the current dir
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	865 os.chdir('/srv/kallithea/')
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	866
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	867 import site
5592 57bae44fd22e docs: consistently use venv instead of pyenv Mads Kiilerich <madski@unity3d.com> parents: 5497 diff changeset	868 site.addsitedir("/srv/kallithea/venv/lib/python2.7/site-packages")
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	869
5789 8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	870 ini = '/srv/kallithea/my.ini'
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	871 from paste.script.util.logging_config import fileConfig
5789 8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	872 fileConfig(ini)
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	873 from paste.deploy import loadapp
8c479b274e03 docs: improve mod_wsgi documentation (Issue #203) Mads Kiilerich <madski@unity3d.com> parents: 5788 diff changeset	874 application = loadapp('config:' + ini)
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	875
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	876 Or using proper virtualenv activation:
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	877
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	878 .. code-block:: python
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	879
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	880 activate_this = '/srv/kallithea/venv/bin/activate_this.py'
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	881 execfile(activate_this, dict(__file__=activate_this))
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	882
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	883 import os
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	884 os.environ['HOME'] = '/srv/kallithea'
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	885
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	886 ini = '/srv/kallithea/kallithea.ini'
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	887 from paste.script.util.logging_config import fileConfig
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	888 fileConfig(ini)
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	889 from paste.deploy import loadapp
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4848 diff changeset	890 application = loadapp('config:' + ini)
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	891
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	892
591 1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	893 Other configuration files
1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	894 -------------------------
1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	895
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	896 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	897 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	898
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5413 diff changeset	899 .. __: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ .
591 1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	900
5433 fbbe80e3322b docs: consistent spacing around headings Mads Kiilerich <madski@unity3d.com> parents: 5426 diff changeset	901
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	902 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	903 .. _python: http://www.python.org/
6334 cc21a2b86a30 docs: update links to Mercurial's website and wiki Anton Shestakov <av6@dwimlabs.net> parents: 5791 diff changeset	904 .. _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	905 .. _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	906 .. _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	907 .. _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	908 .. _Redis: http://redis.io/
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	909 .. _python-ldap: http://www.python-ldap.org/
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	910 .. _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	911 .. _PublishingRepositories: https://www.mercurial-scm.org/wiki/PublishingRepositories

Mercurial > kallithea

annotate docs/setup.rst @ 7099:1969f7dfb6b0