kallithea: docs/setup.rst annotate

annotate docs/setup.rst @ 4848:570a4e40f0bb

docs: improve issue tracker integration docs

author	Andrew Shadura <andrew@shadura.me>
date	Wed, 25 Feb 2015 14:06:27 +0100
parents	a9a1560dad79
children	03bbd33bc084

rev	line source
568 5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	1 .. _setup:
5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	2
2095 17c9393e9645 docs Marcin Kuzminski <marcin@python-works.com> parents: 2076 diff changeset	3 =====
568 5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	4 Setup
5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	5 =====
5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	6
5f481e4e888b updated docs, added sphinx build Marcin Kuzminski <marcin@python-works.com> parents: diff changeset	7
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	8 Setting up Kallithea
1448 b05eb16ea105 fixes #206 Marcin Kuzminski <marcin@python-works.com> parents: 1420 diff changeset	9 --------------------
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	10
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	11 First, you will need to create a Kallithea configuration file. Run the
1309 61a6a7bf2cbd small docs updates Marcin Kuzminski <marcin@python-works.com> parents: 1292 diff changeset	12 following command to do this::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	13
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	14 paster make-config Kallithea production.ini
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	15
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	16 - This will create the file `production.ini` in the current directory. This
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	17 configuration file contains the various settings for Kallithea, e.g proxy
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	18 port, email settings, usage of static files, cache, celery settings and
1309 61a6a7bf2cbd small docs updates Marcin Kuzminski <marcin@python-works.com> parents: 1292 diff changeset	19 logging.
845 a040597b070b docs update Marcin Kuzminski <marcin@python-works.com> parents: 777 diff changeset	20
a040597b070b docs update Marcin Kuzminski <marcin@python-works.com> parents: 777 diff changeset	21
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	22 Next, you need to create the databases used by Kallithea. I recommend that you
2105 926f55b038bc added initial rc-extension module Marcin Kuzminski <marcin@python-works.com> parents: 2095 diff changeset	23 use postgresql or sqlite (default). If you choose a database other than the
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	24 default ensure you properly adjust the db url in your production.ini
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	25 configuration file to use this other database. Kallithea currently supports
2105 926f55b038bc added initial rc-extension module Marcin Kuzminski <marcin@python-works.com> parents: 2095 diff changeset	26 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	27 the following command::
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	28
4185 aaa7c3331186 Rename paster command setup-rhodecode to setup-db Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4182 diff changeset	29 paster setup-db production.ini
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	30
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	31 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	32 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	33 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	34 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	35 up for you.
845 a040597b070b docs update Marcin Kuzminski <marcin@python-works.com> parents: 777 diff changeset	36
2358 69df04ee1e2b added detailed step-by-step installation instruction for windows Marcin Kuzminski <marcin@python-works.com> parents: 2284 diff changeset	37 setup process can be fully automated, example for lazy::
69df04ee1e2b added detailed step-by-step installation instruction for windows Marcin Kuzminski <marcin@python-works.com> parents: 2284 diff changeset	38
4185 aaa7c3331186 Rename paster command setup-rhodecode to setup-db Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4182 diff changeset	39 paster setup-db production.ini --user=nn --password=secret --email=nn@your.kallithea.server --repos=/home/nn/my_repos
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	40
2358 69df04ee1e2b added detailed step-by-step installation instruction for windows Marcin Kuzminski <marcin@python-works.com> parents: 2284 diff changeset	41
4185 aaa7c3331186 Rename paster command setup-rhodecode to setup-db Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4182 diff changeset	42 - The ``setup-db`` command will create all of the needed tables and an
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	43 admin account. When choosing a root path you can either use a new empty
2284 e285aa097a81 new setup-rhodecode command with optional defaults Marcin Kuzminski <marcin@python-works.com> parents: 2105 diff changeset	44 location, or a location which already contains existing repositories. If you
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	45 choose a location which contains existing repositories Kallithea will simply
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	46 add all of the repositories at the chosen location to it's database.
2284 e285aa097a81 new setup-rhodecode command with optional defaults Marcin Kuzminski <marcin@python-works.com> parents: 2105 diff changeset	47 (Note: make sure you specify the correct path to the root).
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	48 - Note: the given path for mercurial_ repositories must be write accessible
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	49 for the application. It's very important since the Kallithea web interface
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	50 will work without write access, but when trying to do a push it will
1309 61a6a7bf2cbd small docs updates Marcin Kuzminski <marcin@python-works.com> parents: 1292 diff changeset	51 eventually fail with permission denied errors unless it has write access.
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	52
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	53 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	54
1123 9472a0150bf0 docs update Marcin Kuzminski <marcin@python-works.com> parents: 1092 diff changeset	55 paster serve production.ini
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	56
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	57 - This command runs the Kallithea server. The web app should be available at the
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	58 127.0.0.1:5000. This ip and port is configurable via the production.ini
845 a040597b070b docs update Marcin Kuzminski <marcin@python-works.com> parents: 777 diff changeset	59 file created in previous step
4185 aaa7c3331186 Rename paster command setup-rhodecode to setup-db Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4182 diff changeset	60 - Use the admin account you created above when running ``setup-db``
2284 e285aa097a81 new setup-rhodecode command with optional defaults Marcin Kuzminski <marcin@python-works.com> parents: 2105 diff changeset	61 to login to the web app.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	62 - 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	63 Remember to update these if needed.
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	64 - In the admin panel you can toggle ldap, anonymous, permissions settings. As
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	65 well as edit more advanced options on users and repositories
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	66
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	67 Optionally users can create `rcextensions` package that extends Kallithea
2105 926f55b038bc added initial rc-extension module Marcin Kuzminski <marcin@python-works.com> parents: 2095 diff changeset	68 functionality. To do this simply execute::
926f55b038bc added initial rc-extension module Marcin Kuzminski <marcin@python-works.com> parents: 2095 diff changeset	69
926f55b038bc added initial rc-extension module Marcin Kuzminski <marcin@python-works.com> parents: 2095 diff changeset	70 paster make-rcext production.ini
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	71
2105 926f55b038bc added initial rc-extension module Marcin Kuzminski <marcin@python-works.com> parents: 2095 diff changeset	72 This will create `rcextensions` package in the same place that your `ini` file
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	73 lives. With `rcextensions` it's possible to add additional mapping for whoosh,
2906 c008f1b0cf62 docs update Marcin Kuzminski <marcin@python-works.com> parents: 2800 diff changeset	74 stats and add additional code into the push/pull/create/delete repo hooks.
c008f1b0cf62 docs update Marcin Kuzminski <marcin@python-works.com> parents: 2800 diff changeset	75 For example for sending signals to build-bots such as jenkins.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	76 Please see the `__init__.py` file inside `rcextensions` package
2105 926f55b038bc added initial rc-extension module Marcin Kuzminski <marcin@python-works.com> parents: 2095 diff changeset	77 for more details.
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	78
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	79
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	80 Using Kallithea with SSH
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	81 ------------------------
8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	82
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	83 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	84 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	85 parallel with Kallithea. (Repository access via ssh is a standard "out of
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	86 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	87 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	88
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	89 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	90 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	91 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	92
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	93 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	94 login accounts have the correct permissions set on the appropriate directories.
61a6a7bf2cbd small docs updates Marcin Kuzminski <marcin@python-works.com> parents: 1292 diff changeset	95 (Note that these permissions are independent of any permissions you have set up
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	96 using the Kallithea web interface.)
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	97
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	98 If your main directory (the same as set in Kallithea settings) is for example
e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	99 set to /home/hg and the repository you are using is named `kallithea`, then
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	100 to clone via ssh you should run::
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	101
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	102 hg clone ssh://user@server.com/home/hg/kallithea
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	103
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	104 Using other external tools such as mercurial-server_ or using ssh key based
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	105 authentication is fully supported.
912 8378122aa408 docs: changelog + setup update Marcin Kuzminski <marcin@python-works.com> parents: 894 diff changeset	106
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	107 Note: In an advanced setup, in order for your ssh access to use the same
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	108 permissions as set up via the Kallithea web interface, you can create an
e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	109 authentication hook to connect to the Kallithea db and runs check functions for
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	110 permissions against that.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	111
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	112 Setting up Whoosh full text search
341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	113 ----------------------------------
341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	114
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	115 Starting from version 1.1 the whoosh index can be build by using the paster
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	116 command ``make-index``. To use ``make-index`` you must specify the configuration
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	117 file that stores the location of the index. You may specify the location of the
8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	118 repositories (`--repo-location`). If not specified, this value is retrieved
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	119 from the Kallithea database. This was required prior to 1.2. Starting from
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	120 version 1.2 it is also possible to specify a comma separated list of
8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	121 repositories (`--index-only`) to build index only on chooses repositories
1408 93cffcb6fd54 Adding documentation for indexer's self-resolving repos location. Jared Bunting <jared.bunting@peachjean.com> parents: 1392 diff changeset	122 skipping any other found in repos location
894 1fed3c9161bb fixes #90 + docs update Marcin Kuzminski <marcin@python-works.com> parents: 881 diff changeset	123
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	124 You may optionally pass the option `-f` to enable a full index rebuild. Without
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	125 the `-f` option, indexing will run always in "incremental" mode.
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	126
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	127 For an incremental index build use::
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	128
3267 7b74079beec9 coding style: fix trailing and leading spaces and tabs Mads Kiilerich <madski@unity3d.com> parents: 3243 diff changeset	129 paster make-index production.ini
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	130
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	131 For a full index rebuild use::
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	132
3267 7b74079beec9 coding style: fix trailing and leading spaces and tabs Mads Kiilerich <madski@unity3d.com> parents: 3243 diff changeset	133 paster make-index production.ini -f
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	134
894 1fed3c9161bb fixes #90 + docs update Marcin Kuzminski <marcin@python-works.com> parents: 881 diff changeset	135
1fed3c9161bb fixes #90 + docs update Marcin Kuzminski <marcin@python-works.com> parents: 881 diff changeset	136 building index just for chosen repositories is possible with such command::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	137
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	138 paster make-index production.ini --index-only=vcs,kallithea
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	139
894 1fed3c9161bb fixes #90 + docs update Marcin Kuzminski <marcin@python-works.com> parents: 881 diff changeset	140
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	141 In order to do periodical index builds and keep your index always up to date.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	142 It's recommended to do a crontab entry for incremental indexing.
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	143 An example entry might look like this::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	144
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	145 /path/to/python/bin/paster make-index /path/to/kallithea/production.ini
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	146
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	147 When using incremental mode (the default) whoosh will check the last
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	148 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	149 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	150 from index.
683 341beaa9edba Implemented whoosh index building as paster command. Marcin Kuzminski <marcin@python-works.com> parents: 597 diff changeset	151
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	152 If you want to rebuild index from scratch, you can use the `-f` flag as above,
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	153 or in the admin panel you can check `build from scratch` flag.
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	154
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	155
1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	156 Setting up LDAP support
1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	157 -----------------------
1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	158
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	159 Kallithea starting from version 1.1 supports ldap authentication. In order
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	160 to use LDAP, you have to install the python-ldap_ package. This package is
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	161 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	162
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	163 using easy_install::
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	164
1123 9472a0150bf0 docs update Marcin Kuzminski <marcin@python-works.com> parents: 1092 diff changeset	165 easy_install python-ldap
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	166
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	167 using pip::
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	168
1123 9472a0150bf0 docs update Marcin Kuzminski <marcin@python-works.com> parents: 1092 diff changeset	169 pip install python-ldap
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	170
770 5f82a00b92b1 docs update Marcin Kuzminski <marcin@python-works.com> parents: 744 diff changeset	171 .. note::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	172 python-ldap requires some certain libs on your system, so before installing
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	173 it check that you have at least `openldap`, and `sasl` libraries.
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	174
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	175 LDAP settings are located in admin->ldap section,
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	176
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	177 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	178
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	179 Connection settings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	180 Enable LDAP = checked
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	181 Host = host.example.org
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	182 Port = 389
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	183 Account = <account>
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	184 Password = <password>
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	185 Connection Security = LDAPS connection
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	186 Certificate Checks = DEMAND
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	187
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	188 Search settings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	189 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	190 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	191 LDAP Search Scope = SUBTREE
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	192
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	193 Attribute mappings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	194 Login Attribute = uid
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	195 First Name Attribute = firstName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	196 Last Name Attribute = lastName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	197 E-mail Attribute = mail
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	198
3801 6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units. Magnus Ericmats <magnus.ericmats@gmail.com> parents: 3622 diff changeset	199 If your user groups are placed in a Organisation Unit (OU) structure the Search Settings configuration differs::
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units. Magnus Ericmats <magnus.ericmats@gmail.com> parents: 3622 diff changeset	200
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units. Magnus Ericmats <magnus.ericmats@gmail.com> parents: 3622 diff changeset	201 Search settings
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units. Magnus Ericmats <magnus.ericmats@gmail.com> parents: 3622 diff changeset	202 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	203 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	204 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	205
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	206 .. _enable_ldap:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	207
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	208 Enable LDAP : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	209 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	210
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	211 .. _ldap_host:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	212
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	213 Host : required
2916 f6685a62e455 Updated docs about LDAP failover server list option Marcin Kuzminski <marcin@python-works.com> parents: 2906 diff changeset	214 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	215 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	216
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	217 .. _Port:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	218
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	219 Port : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	220 389 for un-encrypted LDAP, 636 for SSL-encrypted LDAP.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	221
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	222 .. _ldap_account:
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	223
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	224 Account : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	225 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	226 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	227 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	228
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	229 .. _LDAP Password:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	230
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	231 Password : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	232 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	233 records.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	234
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	235 .. _Enable LDAPS:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	236
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	237 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	238 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	239
c0335c1dee36 added some fixes to LDAP form re-submition, new simples ldap-settings getter. Marcin Kuzminski <marcin@python-works.com> parents: 1284 diff changeset	240 No encryption
c0335c1dee36 added some fixes to LDAP form re-submition, new simples ldap-settings getter. Marcin Kuzminski <marcin@python-works.com> parents: 1284 diff changeset	241 Plain non encrypted connection
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	242
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	243 LDAPS connection
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	244 Enable ldaps connection. It will likely require `Port`_ to be set to
8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	245 a different value (standard LDAPS port is 636). When LDAPS is enabled
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	246 then `Certificate Checks`_ is required.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	247
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	248 START_TLS on LDAP connection
c0335c1dee36 added some fixes to LDAP form re-submition, new simples ldap-settings getter. Marcin Kuzminski <marcin@python-works.com> parents: 1284 diff changeset	249 START TLS connection
992 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 .. _Certificate Checks:
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	252
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	253 Certificate Checks : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	254 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	255 `Enable LDAPS`_ is enabled. Only DEMAND or HARD offer full SSL security
1309 61a6a7bf2cbd small docs updates Marcin Kuzminski <marcin@python-works.com> parents: 1292 diff changeset	256 while the other options are susceptible to man-in-the-middle attacks. SSL
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	257 certificates can be installed to /etc/openldap/cacerts so that the
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	258 DEMAND or HARD options can be used with self-signed certificates or
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	259 certificates that do not have traceable certificates of authority.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	260
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	261 NEVER
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	262 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	263
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	264 ALLOW
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	265 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	266 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	267 session.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	268
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	269 TRY
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	270 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	271 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	272 halts the session.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	273
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	274 DEMAND
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	275 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	276 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	277
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	278 HARD
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	279 The same as DEMAND.
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 .. _Base DN:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	282
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	283 Base DN : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	284 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	285 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	286
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	287 .. _LDAP Filter:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	288
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	289 LDAP Filter : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	290 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	291 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	292 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	293 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	294 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	295
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	296 .. _LDAP Search Scope:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	297
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	298 LDAP Search Scope : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	299 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	300
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	301 BASE
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	302 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	303 want.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	304
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	305 ONELEVEL
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	306 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	307
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	308 SUBTREE
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	309 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	310 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	311 location.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	312
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	313 .. _Login Attribute:
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	314
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	315 Login Attribute : required
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	316 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	317 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	318 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	319 "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	320 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	321 ::
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 (&(LDAPFILTER)(uid=jsmith))
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_attr_firstname:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	326
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	327 First Name Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	328 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	329
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	330 .. _ldap_attr_lastname:
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 Last Name Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	333 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	334
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	335 .. _ldap_attr_email:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	336
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	337 Email Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	338 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	339
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	340 If all data are entered correctly, and python-ldap_ is properly installed
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	341 users should be granted access to Kallithea with ldap accounts. At this
e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	342 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	343 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	344 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	345
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	346 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	347 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	348 will be saved there.
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 Active Directory
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	351 ''''''''''''''''
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	352
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	353 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	354 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	355 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	356 Directory ::
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	357
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	358 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	359 Login Attribute = sAMAccountName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	360 First Name Attribute = givenName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	361 Last Name Attribute = sn
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	362 E-mail Attribute = mail
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 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	365 appropriately configured.
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	366
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	367
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	368 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	369 --------------------------------------------
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	370
4501 a68fc4abeda3 issue #7 remove obsolete configuration domruf <dominikruf@gmail.com> parents: 4448 diff changeset	371 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	372 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	373 clients access the application.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	374
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	375 When these authentication methods are enabled in Kallithea, it uses the
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	376 username that the container/proxy (Apache/Nginx/etc) authenticated and doesn't
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	377 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	378 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	379
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	380 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	381 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	382 administrator can then modify it using Kallithea's admin interface.
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	383 It's also possible for an administrator to create accounts and configure their
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	384 permissions before the user logs in for the first time.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	385
4501 a68fc4abeda3 issue #7 remove obsolete configuration domruf <dominikruf@gmail.com> parents: 4448 diff changeset	386
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	387 Container-based authentication
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	388 ''''''''''''''''''''''''''''''
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	389
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	390 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	391 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	392
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	393 After setting up your container (see `Apache's WSGI config`_), you'd need
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	394 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	395 Kallithea.
1657 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
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	398 Proxy pass-through authentication
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	399 '''''''''''''''''''''''''''''''''
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	400
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	401 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	402 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	403 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	404
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	405 After setting up your proxy solution (see `Apache virtual host reverse proxy example`_,
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	406 `Apache as subdirectory`_ or `Nginx virtual host example`_), you'd need to
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	407 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	408 ``X-Forwarded-User``.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	409
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	410 For example, the following config section for Apache sets a subdirectory in a
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	411 reverse-proxy setup with basic auth::
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	412
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	413 <Location /<someprefix> >
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	414 ProxyPass http://127.0.0.1:5000/<someprefix>
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	415 ProxyPassReverse http://127.0.0.1:5000/<someprefix>
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	416 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	417
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	418 AuthType Basic
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	419 AuthName "Kallithea authentication"
e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	420 AuthUserFile /home/web/kallithea/.htpasswd
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	421 require valid-user
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	422
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	423 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	424
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	425 RewriteEngine On
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	426 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	427 RewriteRule .* - [E=RU:%1]
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	428 RequestHeader set X-Forwarded-User %{RU}e
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	429 </Location>
1657 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
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	432 .. note::
d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	433 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	434 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	435 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	436 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	437
1838 2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	438 Integration with Issue trackers
2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	439 -------------------------------
1657 d2a108366f8f Added documentation for container-based and proxy pass-through authentication Liad Shani <liadff@gmail.com> parents: 1559 diff changeset	440
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	441 Kallithea provides a simple integration with issue trackers. It's possible
1838 2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	442 to define a regular expression that will fetch issue id stored in commit
2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	443 messages and replace that with an url to this issue. To enable this simply
2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	444 uncomment following variables in the ini file::
2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	445
3943 a5bccf34c512 fixed docs error, should be issue_pat Marcin Kuzminski <marcin@python-works.com> parents: 3923 diff changeset	446 issue_pat = (?:^#\|\s#)(\w+)
1870 941dee113136 docs update Marcin Kuzminski <marcin@python-works.com> parents: 1838 diff changeset	447 issue_server_link = https://myissueserver.com/{repo}/issue/{id}
1838 2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	448 issue_prefix = #
2ef309c3175d docs update Marcin Kuzminski <marcin@python-works.com> parents: 1745 diff changeset	449
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	450 `issue_pat` is the regular expression describing which strings in
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	451 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	452 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	453
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	454 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	455
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	456 Matched issues are replaced with the link specified as `issue_server_link`
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	457 {id} is replaced with issue id, and {repo} with repository name.
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	458 Since the # is stripped away, `issue_prefix` is prepended to the link text.
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	459 `issue_prefix` doesn't necessarily need to be #: if you set issue
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	460 prefix to ISSUE- this will generate a URL in format::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	461
8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	462 <a href="https://myissueserver.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	463
4848 570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	464 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	465 the variables. For example::
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	466
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	467 issue_pat_wiki = (?:wiki-)(.+)
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	468 issue_server_link_wiki = https://mywiki.com/{id}
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	469 issue_prefix_wiki = WIKI-
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	470
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	471 With these settings, wiki pages can be referenced as wiki-some-id, and every
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	472 such reference will be transformed into::
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	473
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	474 <a href="https://mywiki.com/some-id">WIKI-some-id</a>
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	475
570a4e40f0bb docs: improve issue tracker integration docs Andrew Shadura <andrew@shadura.me> parents: 4522 diff changeset	476
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	477 Hook management
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	478 ---------------
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	479
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	480 Hooks can be managed in similar way to this used in .hgrc files.
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	481 To access hooks setting click `advanced setup` on Hooks section of Mercurial
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	482 Settings in Admin.
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	483
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	484 There are 4 built in hooks that cannot be changed (only enable/disable by
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	485 checkboxes on previos section).
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	486 To add another custom hook simply fill in first section with
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	487 <name>.<hook_type> and the second one with hook path. Example hooks
4186 7e5f8c12a3fc First step in two-part process to rename directories to kallithea. Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4185 diff changeset	488 can be found at kallithea.lib.hooks.
1467 da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	489
da60cdb41969 doc update - hooks Marcin Kuzminski <marcin@python-works.com> parents: 1448 diff changeset	490
2017 03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	491 Changing default encoding
03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	492 -------------------------
03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	493
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	494 By default Kallithea uses utf8 encoding, starting from 1.3 series this
2017 03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	495 can be changed, simply edit default_encoding in .ini file to desired one.
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	496 This affects many parts in Kallithea including committers names, filenames,
e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	497 encoding of commit messages. In addition Kallithea can detect if `chardet`
e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	498 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	499 when there are encode/decode errors.
03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	500
03a549b35c57 updated setup docs about encoding Marcin Kuzminski <marcin@python-works.com> parents: 1870 diff changeset	501
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	502 Setting Up Celery
aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	503 -----------------
aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	504
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	505 Since version 1.1 celery is configured by the Kallithea ini configuration files.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	506 Simply set use_celery=true in the ini file then add / change the configuration
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	507 variables inside the ini file.
aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	508
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	509 Remember that the ini files use the format with '.' not with '_' like celery.
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	510 So for example setting `BROKER_HOST` in celery means setting `broker.host` in
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	511 the config file.
aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	512
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	513 In order to start using celery run::
938 442ccfe939d0 fixed changelog, and setup docs. Yeeee a 1000 commit :) Marcin Kuzminski <marcin@python-works.com> parents: 929 diff changeset	514
777 aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	515 paster celeryd <configfile.ini>
aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	516
aac24db58ce8 fixed cache problem, Marcin Kuzminski <marcin@python-works.com> parents: 775 diff changeset	517
871 7f9e006aa26f docs update for celeryd Marcin Kuzminski <marcin@python-works.com> parents: 845 diff changeset	518 .. note::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	519 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	520 user that Kallithea runs.
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	521
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	522 HTTPS support
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	523 -------------
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	524
4448 8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	525 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	526
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	527 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	528 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	529
4448 8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	530 - With `https_fixup = true`, the scheme will be taken from the HTTP_X_URL_SCHEME,
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	531 HTTP_X_FORWARDED_SCHEME or HTTP_X_FORWARDED_PROTO HTTP header (default 'http').
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	532 - With `force_https = true` the default will be 'https'.
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks Mads Kiilerich <madski@unity3d.com> parents: 4192 diff changeset	533 - With `use_htsts = true`, it will set Strict-Transport-Security when using https.
871 7f9e006aa26f docs update for celeryd Marcin Kuzminski <marcin@python-works.com> parents: 845 diff changeset	534
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	535 Nginx virtual host example
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	536 --------------------------
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	537
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	538 Sample config for nginx using proxy::
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	539
1745 456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	540 upstream rc {
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	541 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	542 # 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	543 #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	544 #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	545 }
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	546
3850 7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	547 ## gist alias
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	548 server {
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	549 listen 443;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	550 server_name gist.myserver.com;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	551 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	552 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	553
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	554 ssl on;
4182 05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	555 ssl_certificate gist.your.kallithea.server.crt;
05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	556 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	557
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	558 ssl_session_timeout 5m;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	559
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	560 ssl_protocols SSLv3 TLSv1;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	561 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	562 ssl_prefer_server_ciphers on;
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	563
4182 05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	564 rewrite ^/(.+)$ https://your.kallithea.server/_admin/gists/$1;
05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	565 rewrite (.*) https://your.kallithea.server/_admin/gists;
3850 7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	566 }
7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	567
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	568 server {
3243 c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	569 listen 443;
4182 05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	570 server_name your.kallithea.server;
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	571 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	572 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	573
3243 c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	574 ssl on;
4182 05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	575 ssl_certificate your.kallithea.server.crt;
05cabd91f7c3 Change example URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4180 diff changeset	576 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	577
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	578 ssl_session_timeout 5m;
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	579
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	580 ssl_protocols SSLv3 TLSv1;
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	581 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	582 ssl_prefer_server_ciphers on;
c759c0912642 switch to SSL configuration example on nginx Marcin Kuzminski <marcin@python-works.com> parents: 3224 diff changeset	583
3850 7a4df261a375 added alias configuration option for gists. Marcin Kuzminski <marcin@python-works.com> parents: 3801 diff changeset	584 ## 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	585 ## requires static_files = false in .ini file
4186 7e5f8c12a3fc First step in two-part process to rename directories to kallithea. Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4185 diff changeset	586 #root /path/to/installation/kallithea/public;
3917 35c0c62583cd Moved proxy include of nginx to place where Marcin Kuzminski <marcin@python-works.com> parents: 3852 diff changeset	587 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	588 location / {
1745 456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	589 try_files $uri @rhode;
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	590 }
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	591
1745 456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	592 location @rhode {
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	593 proxy_pass http://rc;
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	594 }
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration Marcin Kuzminski <marcin@python-works.com> parents: 1657 diff changeset	595
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	596 }
8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	597
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	598 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	599 pushes or large pushes::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	600
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	601 proxy_redirect off;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	602 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	603 ## 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	604 #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	605 #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	606 proxy_set_header X-Url-Scheme $scheme;
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	607 proxy_set_header X-Host $http_host;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	608 proxy_set_header X-Real-IP $remote_addr;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	609 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	610 proxy_set_header Proxy-host $proxy_host;
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	611 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	612 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	613 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	614 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	615 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	616 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	617 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	618 large_client_header_buffers 8 64k;
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	619
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	620
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	621 Apache virtual host reverse proxy example
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	622 -----------------------------------------
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	623
1092 8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	624 Here is a sample configuration file for apache using proxy::
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	625
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	626 <VirtualHost *:80>
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	627 ServerName hg.myserver.com
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	628 ServerAlias hg.myserver.com
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	629
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	630 <Proxy *>
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	631 Order allow,deny
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	632 Allow from all
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	633 </Proxy>
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	634
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	635 #important !
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	636 #Directive to properly generate url (clone url) for pylons
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	637 ProxyPreserveHost On
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	638
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	639 #kallithea instance
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	640 ProxyPass / http://127.0.0.1:5000/
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	641 ProxyPassReverse / http://127.0.0.1:5000/
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	642
929 c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	643 #to enable https use line below
c44b3c9b9f7f doc fix Marcin Kuzminski <marcin@python-works.com> parents: 912 diff changeset	644 #SetEnvIf X-Url-Scheme https HTTPS=1
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	645
8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	646 </VirtualHost>
881 68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	647
68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	648
68aaa0aca0d2 Updated docs, added apache proxy example config Marcin Kuzminski <marcin@python-works.com> parents: 871 diff changeset	649 Additional tutorial
744 3389f272ece1 docs update Marcin Kuzminski <marcin@python-works.com> parents: 733 diff changeset	650 http://wiki.pylonshq.com/display/pylonscookbook/Apache+as+a+reverse+proxy+for+Pylons
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	651
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	652
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	653 Apache as subdirectory
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	654 ----------------------
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	655
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	656 Apache subdirectory part::
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	657
1226 f17fdbe86ab9 update docs for setup Marcin Kuzminski <marcin@python-works.com> parents: 1123 diff changeset	658 <Location /<someprefix> >
f17fdbe86ab9 update docs for setup Marcin Kuzminski <marcin@python-works.com> parents: 1123 diff changeset	659 ProxyPass http://127.0.0.1:5000/<someprefix>
f17fdbe86ab9 update docs for setup Marcin Kuzminski <marcin@python-works.com> parents: 1123 diff changeset	660 ProxyPassReverse http://127.0.0.1:5000/<someprefix>
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	661 SetEnvIf X-Url-Scheme https HTTPS=1
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	662 </Location>
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	663
1392 00b8fca6886c fixes issue #206 Marcin Kuzminski <marcin@python-works.com> parents: 1386 diff changeset	664 Besides the regular apache setup you will need to add the following line
00b8fca6886c fixes issue #206 Marcin Kuzminski <marcin@python-works.com> parents: 1386 diff changeset	665 into [app:main] section of your .ini file::
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	666
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	667 filter-with = proxy-prefix
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	668
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	669 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	670
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	671 [filter:proxy-prefix]
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	672 use = egg:PasteDeploy#prefix
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	673 prefix = /<someprefix>
1062 053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	674
053983a464e4 docs and readme update Marcin Kuzminski <marcin@python-works.com> parents: 992 diff changeset	675
3622 91ff741c4de5 spelling: chosen Mads Kiilerich <madski@unity3d.com> parents: 3492 diff changeset	676 then change <someprefix> into your chosen prefix
1226 f17fdbe86ab9 update docs for setup Marcin Kuzminski <marcin@python-works.com> parents: 1123 diff changeset	677
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	678 Apache's WSGI config
5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	679 --------------------
5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	680
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	681 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	682 that, you'll need to:
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	683
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	684 - 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	685 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	686
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	687 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	688
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	689 - Enable mod_wsgi::
1559 a9fef2e6c1ff Syntax correction on the recently changed documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1558 diff changeset	690
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	691 a2enmod wsgi
1559 a9fef2e6c1ff Syntax correction on the recently changed documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1558 diff changeset	692
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	693 - Create a wsgi dispatch script, like the one below. Make sure you
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	694 check 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	695 and its Python Virtual Environment.
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	696 - Enable the WSGIScriptAlias directive for the wsgi dispatch script,
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	697 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	698 correctly specified.
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	699
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	700 Here is a sample excerpt from an Apache Virtual Host configuration file::
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	701
2800 6540ee9179da updated apache wsgi example ref #535 Marcin Kuzminski <marcin@python-works.com> parents: 2748 diff changeset	702 WSGIDaemonProcess pylons \
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	703 threads=4 \
4522 a9a1560dad79 setup: clarify that we only support 2.6 and 2.7 Mads Kiilerich <madski@unity3d.com> parents: 4501 diff changeset	704 python-path=/home/web/kallithea/pyenv/lib/python2.7/site-packages
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	705 WSGIScriptAlias / /home/web/kallithea/dispatch.wsgi
2076 77d215d6121f docs on apache WSGI update Marcin Kuzminski <marcin@python-works.com> parents: 2017 diff changeset	706 WSGIPassAuthorization On
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	707
2800 6540ee9179da updated apache wsgi example ref #535 Marcin Kuzminski <marcin@python-works.com> parents: 2748 diff changeset	708 .. note::
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	709 when running apache as root please add: `user=www-data group=www-data`
2800 6540ee9179da updated apache wsgi example ref #535 Marcin Kuzminski <marcin@python-works.com> parents: 2748 diff changeset	710 into above configuration
6540ee9179da updated apache wsgi example ref #535 Marcin Kuzminski <marcin@python-works.com> parents: 2748 diff changeset	711
6540ee9179da updated apache wsgi example ref #535 Marcin Kuzminski <marcin@python-works.com> parents: 2748 diff changeset	712 .. note::
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	713 Running Kallithea in multiprocess mode in apache is not supported,
3335 2d4e1f5e854e docs updates Marcin Kuzminski <marcin@python-works.com> parents: 3267 diff changeset	714 make sure you don't specify `processes=num` directive in the config
2800 6540ee9179da updated apache wsgi example ref #535 Marcin Kuzminski <marcin@python-works.com> parents: 2748 diff changeset	715
6540ee9179da updated apache wsgi example ref #535 Marcin Kuzminski <marcin@python-works.com> parents: 2748 diff changeset	716
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	717 Example wsgi dispatch script::
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	718
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	719 import os
5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	720 os.environ["HGENCODING"] = "UTF-8"
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	721 os.environ['PYTHON_EGG_CACHE'] = '/home/web/kallithea/.egg-cache'
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	722
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	723 # sometimes it's needed to set the curent dir
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	724 os.chdir('/home/web/kallithea/')
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	725
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	726 import site
4522 a9a1560dad79 setup: clarify that we only support 2.6 and 2.7 Mads Kiilerich <madski@unity3d.com> parents: 4501 diff changeset	727 site.addsitedir("/home/web/kallithea/pyenv/lib/python2.7/site-packages")
3224 8b8edfc25856 whitespace cleanup Marcin Kuzminski <marcin@python-works.com> parents: 2916 diff changeset	728
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	729 from paste.deploy import loadapp
5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	730 from paste.script.util.logging_config import fileConfig
5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	731
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	732 fileConfig('/home/web/kallithea/production.ini')
e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	733 application = loadapp('config:/home/web/kallithea/production.ini')
1386 5a31d387f347 Added example wsgi config into docs Marcin Kuzminski <marcin@python-works.com> parents: 1309 diff changeset	734
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	735 Note: when using mod_wsgi you'll need to install the same version of
4192 e73a69cb98dc Rename some strings examples and commands in documentation Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4186 diff changeset	736 Mercurial that's inside Kallithea's virtualenv also on the system's Python
1558 662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	737 environment.
662173ba1846 Improvements to mod_wsgi setup documentation. Augusto Herrmann <augusto.herrmann@planejamento.gov.br> parents: 1467 diff changeset	738
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	739
591 1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	740 Other configuration files
1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	741 -------------------------
1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	742
2601 aa90719e8520 Added troubleshooting section to docs Marcin Kuzminski <marcin@python-works.com> parents: 2358 diff changeset	743 Some example init.d scripts can be found in init.d directory::
707 1105531ae572 docs update, added ldap section, added troubleshooting section Marcin Kuzminski <marcin@python-works.com> parents: 683 diff changeset	744
4179 010e9532801a Change bitbucket and hosting URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4073 diff changeset	745 https://kallithea-scm.org/repos/kallithea/files/tip/init.d/
591 1e2adb37cab6 docs update Marcin Kuzminski <marcin@python-works.com> parents: 572 diff changeset	746
572 a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	747 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	748 .. _python: http://www.python.org/
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	749 .. _mercurial: http://mercurial.selenic.com/
a60cd29ba7e2 more docs update Marcin Kuzminski <marcin@python-works.com> parents: 568 diff changeset	750 .. _celery: http://celeryproject.org/
992 c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	751 .. _rabbitmq: http://www.rabbitmq.com/
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information). Thayne Harbaugh <thayne@fusionio.com> parents: 968 diff changeset	752 .. _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	753 .. _mercurial-server: http://www.lshift.net/mercurial-server.html
8af52e1224ff merge docs in beta with those corrected by Jason Harris Marcin Kuzminski <marcin@python-works.com> parents: 1062 diff changeset	754 .. _PublishingRepositories: http://mercurial.selenic.com/wiki/PublishingRepositories
4179 010e9532801a Change bitbucket and hosting URL Bradley M. Kuhn <bkuhn@sfconservancy.org> parents: 4073 diff changeset	755 .. _Issues tracker: https://bitbucket.org/conservancy/kallithea/issues

Mercurial > kallithea

annotate docs/setup.rst @ 4848:570a4e40f0bb