Mercurial > kallithea

annotate docs/setup.rst @ 6898:a8b9f2d68e7d

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