Mercurial > kallithea

annotate docs/setup.rst @ 4925:56cd202b777e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: move all instructions on Celery to Setup Instead of having some info on Celery in both Installation and Setup, move everything to Setup and do some rewrite. Additionally, update some outdated URLs and remove unused link targets.
author Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
date Tue, 17 Mar 2015 20:47:00 +0100
parents 6892b0515af9
children 4e6dfdb3fa01
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
14 paster make-config Kallithea my.ini
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
15
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
16 - This will create the file `my.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
4925
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
22 Next, you need to create the databases used by Kallithea. It is recommended to
4914
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4902
diff changeset
23 use PostgreSQL or SQLite (default). If you choose a database other than the
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4902
diff changeset
24 default ensure you properly adjust the database URL in your my.ini
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
25 configuration file to use this other database. Kallithea currently supports
4914
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4902
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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
29 paster setup-db my.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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
39 paster setup-db my.ini --user=nn --password=secret --email=nn@your.kallithea.server --repos=/srv/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
4914
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4902
diff changeset
45 choose a location which contains existing repositories Kallithea will
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4902
diff changeset
46 add all of the repositories at the chosen location to its 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).
4914
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4902
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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
55 paster serve my.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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
58 127.0.0.1:5000. This ip and port is configurable via the my.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.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
64 - In the admin panel you can toggle LDAP, anonymous, permissions settings. As
1092
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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
70 paster make-rcext my.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.
4914
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4902
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
4914
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4902
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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
99 set to **/srv/repos** 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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
102 hg clone ssh://user@server.com//srv/repos/kallithea
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
115 The whoosh index can be build by using the paster
1092
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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
119 from the Kallithea database.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
120 It is also possible to specify a comma separated list of
3224
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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
129 paster make-index my.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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
133 paster make-index my.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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
138 paster make-index my.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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
145 /path/to/python/bin/paster make-index /path/to/kallithea/my.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
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
159 Kallithea 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
1123
9472a0150bf0 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1092
diff changeset
163 pip install python-ldap
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
164
770
5f82a00b92b1 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 744
diff changeset
165 .. note::
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
166 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
167 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
168
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
169 LDAP settings are located in Admin->LDAP section.
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
170
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
171 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
172
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
173 Connection settings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
174 Enable LDAP = checked
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
175 Host = host.example.org
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
176 Port = 389
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
177 Account = <account>
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
178 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
179 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
180 Certificate Checks = DEMAND
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
181
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
182 Search settings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
183 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
184 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
185 LDAP Search Scope = SUBTREE
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
186
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
187 Attribute mappings
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
188 Login Attribute = uid
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
189 First Name Attribute = firstName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
190 Last Name Attribute = lastName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
191 E-mail Attribute = mail
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
192
3801
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units.
Magnus Ericmats <magnus.ericmats@gmail.com>
parents: 3622
diff changeset
193 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
194
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units.
Magnus Ericmats <magnus.ericmats@gmail.com>
parents: 3622
diff changeset
195 Search settings
6bad83d27fc1 Documentation: How to setup LDAP Filter when using Organisational Units.
Magnus Ericmats <magnus.ericmats@gmail.com>
parents: 3622
diff changeset
196 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
197 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
198 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
199
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
200 .. _enable_ldap:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
201
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
202 Enable LDAP : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
203 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
204
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
205 .. _ldap_host:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
206
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
207 Host : required
2916
f6685a62e455 Updated docs about LDAP failover server list option
Marcin Kuzminski <marcin@python-works.com>
parents: 2906
diff changeset
208 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
209 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
210
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
211 .. _Port:
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 Port : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
214 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
215
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
216 .. _ldap_account:
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
217
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
218 Account : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
219 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
220 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
221 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
222
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
223 .. _LDAP Password:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
224
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
225 Password : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
226 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
227 records.
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 .. _Enable LDAPS:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
230
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
231 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
232 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
233
c0335c1dee36 added some fixes to LDAP form re-submition, new simples ldap-settings getter.
Marcin Kuzminski <marcin@python-works.com>
parents: 1284
diff changeset
234 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
235 Plain non encrypted connection
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
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 LDAPS connection
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
238 Enable LDAPS connections. It will likely require `Port`_ to be set to
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
239 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
240 then `Certificate Checks`_ is required.
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
241
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
242 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
243 START TLS connection
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
244
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
245 .. _Certificate Checks:
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
246
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
247 Certificate Checks : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
248 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
249 `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
250 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
251 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
252 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
253 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
254
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
255 NEVER
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
256 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
257
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
258 ALLOW
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
259 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
260 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
261 session.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
262
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
263 TRY
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
264 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
265 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
266 halts the session.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
267
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
268 DEMAND
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
269 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
270 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
271
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
272 HARD
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
273 The same as DEMAND.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
274
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
275 .. _Base DN:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
276
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
277 Base DN : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
278 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
279 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
280
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
281 .. _LDAP Filter:
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 LDAP Filter : optional
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
284 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
285 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
286 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
287 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
288 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
289
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
290 .. _LDAP Search Scope:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
291
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
292 LDAP Search Scope : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
293 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
294
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
295 BASE
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
296 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
297 want.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
298
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
299 ONELEVEL
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
300 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
301
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
302 SUBTREE
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
303 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
304 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
305 location.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
306
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
307 .. _Login Attribute:
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
308
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
309 Login Attribute : required
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
310 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
311 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
312 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
313 "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
314 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
315 ::
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
316
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
317 (&(LDAPFILTER)(uid=jsmith))
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
318
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
319 .. _ldap_attr_firstname:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
320
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
321 First Name Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
322 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
323
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
324 .. _ldap_attr_lastname:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
325
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
326 Last Name Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
327 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
328
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
329 .. _ldap_attr_email:
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
330
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
331 Email Attribute : required
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
332 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
333
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
334 If all data are entered correctly, and python-ldap_ is properly installed
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
335 users should be granted access to Kallithea with LDAP accounts. At this
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
336 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
337 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
338 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
339
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
340 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
341 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
342 will be saved there.
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
343
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
344 Active Directory
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
345 ''''''''''''''''
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
346
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
347 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
348 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
349 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
350 Directory ::
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
351
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
352 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
353 Login Attribute = sAMAccountName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
354 First Name Attribute = givenName
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
355 Last Name Attribute = sn
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
356 E-mail Attribute = mail
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
357
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
358 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
359 appropriately configured.
777
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
360
1467
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
361
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
362 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
363 --------------------------------------------
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
364
4501
a68fc4abeda3 issue #7 remove obsolete configuration
domruf <dominikruf@gmail.com>
parents: 4448
diff changeset
365 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
366 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
367 clients access the application.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
368
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
369 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
370 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
371 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
372 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
373
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
374 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
375 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
376 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
377 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
378 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
379
4501
a68fc4abeda3 issue #7 remove obsolete configuration
domruf <dominikruf@gmail.com>
parents: 4448
diff changeset
380
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
381 Container-based authentication
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
382 ''''''''''''''''''''''''''''''
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
383
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
384 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
385 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
386
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
387 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
388 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
389 Kallithea.
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
390
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
391
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
392 Proxy pass-through authentication
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
393 '''''''''''''''''''''''''''''''''
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
394
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
395 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
396 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
397 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
398
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
399 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
400 `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
401 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
402 ``X-Forwarded-User``.
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
403
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
404 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
405 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
406
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
407 <Location /<someprefix> >
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
408 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
409 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
410 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
411
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
412 AuthType Basic
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
413 AuthName "Kallithea authentication"
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
414 AuthUserFile /srv/kallithea/.htpasswd
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
415 require valid-user
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
416
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
417 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
418
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
419 RewriteEngine On
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
420 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
421 RewriteRule .* - [E=RU:%1]
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
422 RequestHeader set X-Forwarded-User %{RU}e
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
423 </Location>
1657
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
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
426 .. note::
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
427 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
428 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
429 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
430 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
431
1838
2ef309c3175d docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1745
diff changeset
432 Integration with Issue trackers
2ef309c3175d docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1745
diff changeset
433 -------------------------------
1657
d2a108366f8f Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents: 1559
diff changeset
434
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
435 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
436 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
437 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
438 uncomment following variables in the ini file::
2ef309c3175d docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1745
diff changeset
439
3943
a5bccf34c512 fixed docs error, should be issue_pat
Marcin Kuzminski <marcin@python-works.com>
parents: 3923
diff changeset
440 issue_pat = (?:^#|\s#)(\w+)
1870
941dee113136 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1838
diff changeset
441 issue_server_link = https://myissueserver.com/{repo}/issue/{id}
1838
2ef309c3175d docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1745
diff changeset
442 issue_prefix = #
2ef309c3175d docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1745
diff changeset
443
4848
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
444 `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
445 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
446 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
447
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
448 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
449
4848
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
450 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
451 {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
452 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
453 `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
454 prefix to ISSUE- this will generate a URL in format::
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
455
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
456 <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
457
4848
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
458 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
459 the variables. For example::
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
460
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
461 issue_pat_wiki = (?:wiki-)(.+)
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
462 issue_server_link_wiki = https://mywiki.com/{id}
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
463 issue_prefix_wiki = WIKI-
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
464
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
465 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
466 such reference will be transformed into::
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
467
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
468 <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
469
570a4e40f0bb docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents: 4522
diff changeset
470
1467
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
471 Hook management
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
472 ---------------
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
473
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
474 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
475 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
476 Settings in Admin.
1467
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
477
da60cdb41969 doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents: 1448
diff changeset
478 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
479 checkboxes on previos section).
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
480 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
481 <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
482 can be found at *kallithea.lib.hooks*.
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
2017
03a549b35c57 updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents: 1870
diff changeset
485 Changing default encoding
03a549b35c57 updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents: 1870
diff changeset
486 -------------------------
03a549b35c57 updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents: 1870
diff changeset
487
4914
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4902
diff changeset
488 By default, Kallithea uses UTF-8 encoding.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
489 It is configurable as `default_encoding` in the .ini file.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
490 This affects many parts in Kallithea including user names, filenames, and
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
491 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
492 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
493 when there are encode/decode errors.
03a549b35c57 updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents: 1870
diff changeset
494
03a549b35c57 updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents: 1870
diff changeset
495
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
496 Celery configuration
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
497 --------------------
777
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
498
4925
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
499 Kallithea can use the distributed task queue system Celery_ to run tasks like
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
500 cloning repositories or sending mails.
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
501
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
502 Kallithea will in most setups work perfectly fine out of the box (without
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
503 Celery), executing all tasks in the web server process. Some tasks can however
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
504 take some time to run and it can be better to run such tasks asynchronously in
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
505 a separate process so the web server can focus on serving web requests.
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
506
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
507 For installation and configuration of Celery, see the `Celery documentation`_.
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
508 Note that Celery requires a message broker service like RabbitMQ_ (recommended)
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
509 or Redis_.
777
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
510
4925
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
511 The use of Celery is configured in the Kallithea ini configuration file.
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
512 To enable it, simply set::
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
513
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
514 use_celery = true
777
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
515
4925
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
516 and add or change the celery.* and broker.* configuration variables.
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
517
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
518 Remember that the ini files use the format with '.' and not with '_' like
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
519 Celery. So for example setting `BROKER_HOST` in Celery means setting
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
520 `broker.host` in the configuration file.
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
521
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
522 To start the Celery process, run::
938
442ccfe939d0 fixed changelog, and setup docs. Yeeee a 1000 commit :)
Marcin Kuzminski <marcin@python-works.com>
parents: 929
diff changeset
523
777
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
524 paster celeryd <configfile.ini>
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
525
aac24db58ce8 fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents: 775
diff changeset
526
871
7f9e006aa26f docs update for celeryd
Marcin Kuzminski <marcin@python-works.com>
parents: 845
diff changeset
527 .. note::
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
528 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
529 user that Kallithea runs.
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
530
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
531 HTTPS support
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
532 -------------
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
533
4448
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks
Mads Kiilerich <madski@unity3d.com>
parents: 4192
diff changeset
534 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
535
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks
Mads Kiilerich <madski@unity3d.com>
parents: 4192
diff changeset
536 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
537 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
538
4448
8e26c46e9abe https: introduce https_fixup config setting to enable the special https hacks
Mads Kiilerich <madski@unity3d.com>
parents: 4192
diff changeset
539 - 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
540 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
541 - 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
542 - 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
543
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
544 Nginx virtual host example
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
545 --------------------------
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
546
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
547 Sample config for nginx using proxy::
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
548
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
549 upstream kallithea {
1745
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
550 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
551 # 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
552 #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
553 #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
554 }
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
555
3850
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
556 ## gist alias
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
557 server {
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
558 listen 443;
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
559 server_name gist.myserver.com;
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
560 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
561 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
562
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
563 ssl on;
4182
05cabd91f7c3 Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4180
diff changeset
564 ssl_certificate gist.your.kallithea.server.crt;
05cabd91f7c3 Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4180
diff changeset
565 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
566
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
567 ssl_session_timeout 5m;
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
568
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
569 ssl_protocols SSLv3 TLSv1;
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
570 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
571 ssl_prefer_server_ciphers on;
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
572
4182
05cabd91f7c3 Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4180
diff changeset
573 rewrite ^/(.+)$ https://your.kallithea.server/_admin/gists/$1;
05cabd91f7c3 Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4180
diff changeset
574 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
575 }
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
576
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
577 server {
3243
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
578 listen 443;
4182
05cabd91f7c3 Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4180
diff changeset
579 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
580 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
581 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
582
3243
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
583 ssl on;
4182
05cabd91f7c3 Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4180
diff changeset
584 ssl_certificate your.kallithea.server.crt;
05cabd91f7c3 Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4180
diff changeset
585 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
586
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
587 ssl_session_timeout 5m;
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
588
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
589 ssl_protocols SSLv3 TLSv1;
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
590 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
591 ssl_prefer_server_ciphers on;
c759c0912642 switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents: 3224
diff changeset
592
3850
7a4df261a375 added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents: 3801
diff changeset
593 ## 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
594 ## 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
595 #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
596 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
597 location / {
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
598 try_files $uri @kallithea;
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
599 }
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
600
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
601 location @kallithea {
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
602 proxy_pass http://kallithea;
1745
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
603 }
456e1e3ce4eb fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents: 1657
diff changeset
604
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
605 }
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
606
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
607 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
608 pushes or large pushes::
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
609
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
610 proxy_redirect off;
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
611 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
612 ## 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
613 #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
614 #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
615 proxy_set_header X-Url-Scheme $scheme;
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
616 proxy_set_header X-Host $http_host;
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
617 proxy_set_header X-Real-IP $remote_addr;
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
618 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
619 proxy_set_header Proxy-host $proxy_host;
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
620 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
621 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
622 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
623 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
624 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
625 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
626 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
627 large_client_header_buffers 8 64k;
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
628
881
68aaa0aca0d2 Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents: 871
diff changeset
629
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
630 Apache virtual host reverse proxy example
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
631 -----------------------------------------
881
68aaa0aca0d2 Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents: 871
diff changeset
632
1092
8af52e1224ff merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents: 1062
diff changeset
633 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
634
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
635 <VirtualHost *:80>
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
636 ServerName hg.myserver.com
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
637 ServerAlias hg.myserver.com
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
638
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
639 <Proxy *>
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
640 Order allow,deny
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
641 Allow from all
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
642 </Proxy>
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
643
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
644 #important !
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
645 #Directive to properly generate url (clone url) for pylons
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
646 ProxyPreserveHost On
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
647
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
648 #kallithea instance
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
649 ProxyPass / http://127.0.0.1:5000/
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
650 ProxyPassReverse / http://127.0.0.1:5000/
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
651
929
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
652 #to enable https use line below
c44b3c9b9f7f doc fix
Marcin Kuzminski <marcin@python-works.com>
parents: 912
diff changeset
653 #SetEnvIf X-Url-Scheme https HTTPS=1
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
654
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
655 </VirtualHost>
881
68aaa0aca0d2 Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents: 871
diff changeset
656
68aaa0aca0d2 Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents: 871
diff changeset
657
68aaa0aca0d2 Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents: 871
diff changeset
658 Additional tutorial
4915
6892b0515af9 docs: replace a dead link to the pylons cookbook
Andrew Shadura <andrew@shadura.me>
parents: 4914
diff changeset
659 http://pylonsbook.com/en/1.1/deployment.html#using-apache-to-proxy-requests-to-pylons
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
660
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
661
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
662 Apache as subdirectory
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
663 ----------------------
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
664
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
665 Apache subdirectory part::
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
666
1226
f17fdbe86ab9 update docs for setup
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
667 <Location /<someprefix> >
f17fdbe86ab9 update docs for setup
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
668 ProxyPass http://127.0.0.1:5000/<someprefix>
f17fdbe86ab9 update docs for setup
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
669 ProxyPassReverse http://127.0.0.1:5000/<someprefix>
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
670 SetEnvIf X-Url-Scheme https HTTPS=1
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
671 </Location>
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
672
1392
00b8fca6886c fixes issue #206
Marcin Kuzminski <marcin@python-works.com>
parents: 1386
diff changeset
673 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
674 into [app:main] section of your .ini file::
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
675
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
676 filter-with = proxy-prefix
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
677
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
678 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
679
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
680 [filter:proxy-prefix]
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
681 use = egg:PasteDeploy#prefix
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
682 prefix = /<someprefix>
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
683
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 992
diff changeset
684
3622
91ff741c4de5 spelling: chosen
Mads Kiilerich <madski@unity3d.com>
parents: 3492
diff changeset
685 then change <someprefix> into your chosen prefix
1226
f17fdbe86ab9 update docs for setup
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
686
1386
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
687 Apache's WSGI config
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
688 --------------------
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
689
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
690 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
691 that, you'll need to:
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
692
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
693 - 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
694 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
695
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
696 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
697
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
698 - Enable mod_wsgi::
1559
a9fef2e6c1ff Syntax correction on the recently changed documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1558
diff changeset
699
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
700 a2enmod wsgi
1559
a9fef2e6c1ff Syntax correction on the recently changed documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1558
diff changeset
701
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
702 - 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
703 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
704 and its Python Virtual Environment.
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
705 - 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
706 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
707 correctly specified.
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
708
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
709 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
710
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
711 WSGIDaemonProcess kallithea \
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
712 processes=1 threads=4 \
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
713 python-path=/srv/kallithea/pyenv/lib/python2.7/site-packages
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
714 WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
2076
77d215d6121f docs on apache WSGI update
Marcin Kuzminski <marcin@python-works.com>
parents: 2017
diff changeset
715 WSGIPassAuthorization On
1386
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
716
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
717 Or if using a dispatcher wsgi script with proper virtualenv activation::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
718
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
719 WSGIDaemonProcess kallithea processes=1 threads=4
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
720 WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
721 WSGIPassAuthorization On
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
722
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
723
2800
6540ee9179da updated apache wsgi example ref #535
Marcin Kuzminski <marcin@python-works.com>
parents: 2748
diff changeset
724 .. note::
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
725 When running apache as root, please make sure it doesn't run Kallithea as
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
726 root, for examply by adding: `user=www-data group=www-data` to the configuration.
2800
6540ee9179da updated apache wsgi example ref #535
Marcin Kuzminski <marcin@python-works.com>
parents: 2748
diff changeset
727
6540ee9179da updated apache wsgi example ref #535
Marcin Kuzminski <marcin@python-works.com>
parents: 2748
diff changeset
728 .. note::
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
729 If running Kallithea in multiprocess mode,
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
730 make sure you set `instance_id = \*` in the configuration so each process
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
731 gets it's own cache invalidationkey.
2800
6540ee9179da updated apache wsgi example ref #535
Marcin Kuzminski <marcin@python-works.com>
parents: 2748
diff changeset
732
6540ee9179da updated apache wsgi example ref #535
Marcin Kuzminski <marcin@python-works.com>
parents: 2748
diff changeset
733
1386
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
734 Example wsgi dispatch script::
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
735
1386
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
736 import os
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
737 os.environ["HGENCODING"] = "UTF-8"
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
738 os.environ['PYTHON_EGG_CACHE'] = '/srv/kallithea/.egg-cache'
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
739
1386
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
740 # sometimes it's needed to set the curent dir
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
741 os.chdir('/srv/kallithea/')
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
742
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
743 import site
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
744 site.addsitedir("/srv/kallithea/pyenv/lib/python2.7/site-packages")
3224
8b8edfc25856 whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents: 2916
diff changeset
745
1386
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
746 from paste.deploy import loadapp
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
747 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
748
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
749 fileConfig('/srv/kallithea/my.ini')
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
750 application = loadapp('config:/srv/kallithea/my.ini')
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
751
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
752 Or using proper virtualenv activation::
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
753
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
754 activate_this = '/srv/kallithea/venv/bin/activate_this.py'
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
755 execfile(activate_this,dict(__file__=activate_this))
1386
5a31d387f347 Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents: 1309
diff changeset
756
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
757 import os
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
758 os.environ['HOME'] = '/srv/kallithea'
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
759
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
760 ini = '/srv/kallithea/kallithea.ini'
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
761 from paste.script.util.logging_config import fileConfig
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
762 fileConfig(ini)
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
763 from paste.deploy import loadapp
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
764 application = loadapp('config:' + ini)
1558
662173ba1846 Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents: 1467
diff changeset
765
707
1105531ae572 docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents: 683
diff changeset
766
591
1e2adb37cab6 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 572
diff changeset
767 Other configuration files
1e2adb37cab6 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 572
diff changeset
768 -------------------------
1e2adb37cab6 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 572
diff changeset
769
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4848
diff changeset
770 Some example init.d scripts can be found in init.d directory: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/
591
1e2adb37cab6 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 572
diff changeset
771
572
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
772 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
a60cd29ba7e2 more docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 568
diff changeset
773 .. _python: http://www.python.org/
4914
95fe05b1e5f8 docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents: 4902
diff changeset
774 .. _Mercurial: http://mercurial.selenic.com/
4925
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
775 .. _Celery: http://celeryproject.org/
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
776 .. _Celery documentation: http://docs.celeryproject.org/en/latest/getting-started/index.html
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
777 .. _RabbitMQ: http://www.rabbitmq.com/
56cd202b777e docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4915
diff changeset
778 .. _Redis: http://redis.io/
992
c03d16787b5c Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents: 968
diff changeset
779 .. _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
780 .. _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
781 .. _PublishingRepositories: http://mercurial.selenic.com/wiki/PublishingRepositories