Mercurial > kallithea
annotate docs/setup.rst @ 6460:63460acc2569
pullrequests: refactor default title code
This refactoring simply emphasizes that the origin reference used to
generate the default title is not always the same as the one actually
used to create the pull request; for PRs not from a branch head, the
branch name is stored so it can be used for creating new iterations.
author | Søren Løvborg <sorenl@unity3d.com> |
---|---|
date | Fri, 06 Jan 2017 14:57:19 +0100 |
parents | d0f6bd6190c8 |
children | 2c3d30095d5e |
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 | 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 | 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 |
4902 | 14 paster make-config Kallithea 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 |
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
19 settings, and logging. |
845 | 20 |
4902 | 21 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
|
22 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
|
23 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
|
24 configuration file to use this other database. Kallithea currently supports |
4914
95fe05b1e5f8
docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents:
4902
diff
changeset
|
25 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
|
26 the following command:: |
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
27 |
4902 | 28 paster setup-db my.ini |
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
29 |
1092
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
30 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
|
31 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
|
32 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
|
33 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
|
34 up for you. |
845 | 35 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
36 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
|
37 Example:: |
2358
69df04ee1e2b
added detailed step-by-step installation instruction for windows
Marcin Kuzminski <marcin@python-works.com>
parents:
2284
diff
changeset
|
38 |
5497
12b47803189f
cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents:
5496
diff
changeset
|
39 paster setup-db 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
|
40 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
41 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
|
42 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
|
43 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
|
44 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
|
45 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
|
46 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
|
47 path to the root). |
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
48 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
49 .. 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
|
50 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
|
51 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
|
52 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
|
53 denied errors unless it has write access. |
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
54 |
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
55 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
|
56 |
4902 | 57 paster serve my.ini |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
58 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
59 - 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
|
60 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
|
61 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
|
62 - 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
|
63 - 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
|
64 Remember to update these if needed. |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
65 - 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
|
66 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
|
67 repositories. |
1092
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
68 |
5077
faf943716616
rcextensions: cleanup of code and documentation
Mads Kiilerich <madski@unity3d.com>
parents:
4955
diff
changeset
|
69 |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
70 Using Kallithea with SSH |
912
8378122aa408
docs: changelog + setup update
Marcin Kuzminski <marcin@python-works.com>
parents:
894
diff
changeset
|
71 ------------------------ |
8378122aa408
docs: changelog + setup update
Marcin Kuzminski <marcin@python-works.com>
parents:
894
diff
changeset
|
72 |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
73 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
|
74 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
|
75 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
|
76 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
|
77 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
|
78 |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
79 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
|
80 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
|
81 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
|
82 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
83 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
|
84 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
|
85 |
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
86 .. 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
|
87 have set up using the Kallithea web interface. |
912
8378122aa408
docs: changelog + setup update
Marcin Kuzminski <marcin@python-works.com>
parents:
894
diff
changeset
|
88 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
89 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
|
90 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
|
91 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
|
92 |
5497
12b47803189f
cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents:
5496
diff
changeset
|
93 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
|
94 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
95 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
|
96 authentication is fully supported. |
912
8378122aa408
docs: changelog + setup update
Marcin Kuzminski <marcin@python-works.com>
parents:
894
diff
changeset
|
97 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
98 .. 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
|
99 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
|
100 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
|
101 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
|
102 against that. |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
103 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5426
diff
changeset
|
104 |
683
341beaa9edba
Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents:
597
diff
changeset
|
105 Setting up Whoosh full text search |
341beaa9edba
Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents:
597
diff
changeset
|
106 ---------------------------------- |
341beaa9edba
Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents:
597
diff
changeset
|
107 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
108 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
|
109 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
110 .. __: https://pythonhosted.org/Whoosh/ |
683
341beaa9edba
Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents:
597
diff
changeset
|
111 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
112 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
|
113 |
4902 | 114 paster make-index my.ini |
683
341beaa9edba
Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents:
597
diff
changeset
|
115 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
116 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
|
117 |
4902 | 118 paster make-index my.ini -f |
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
119 |
5855 | 120 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
|
121 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
|
122 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
123 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
|
124 |
4902 | 125 paster make-index my.ini --index-only=vcs,kallithea |
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
126 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
127 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
|
128 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
|
129 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
130 0 3 * * * /path/to/virtualenv/bin/paster make-index /path/to/kallithea/my.ini |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
131 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
132 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
|
133 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
|
134 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
|
135 from index. |
683
341beaa9edba
Implemented whoosh index building as paster command.
Marcin Kuzminski <marcin@python-works.com>
parents:
597
diff
changeset
|
136 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
137 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
|
138 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
|
139 |
5788
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5592
diff
changeset
|
140 .. _ldap-setup: |
707
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
141 |
5815 | 142 |
707
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
143 Setting up LDAP support |
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
144 ----------------------- |
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
145 |
4902 | 146 Kallithea supports LDAP authentication. In order |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
147 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
|
148 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
|
149 |
1123 | 150 pip install python-ldap |
707
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
151 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
152 .. 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
|
153 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
|
154 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
|
155 |
5426
66f1b9745905
docs: update menu navigation notation to use *Menu > Menu Item*
Søren Løvborg <sorenl@unity3d.com>
parents:
5425
diff
changeset
|
156 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
|
157 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
|
158 |
4902 | 159 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
|
160 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
161 Connection settings |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
162 Enable LDAP = checked |
5497
12b47803189f
cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents:
5496
diff
changeset
|
163 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
|
164 Account = <account> |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
165 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
|
166 Connection Security = LDAPS |
992
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
167 Certificate Checks = DEMAND |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
168 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
169 Search settings |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
170 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
|
171 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
|
172 LDAP Search Scope = SUBTREE |
707
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
173 |
992
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
174 Attribute mappings |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
175 Login Attribute = uid |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
176 First Name Attribute = firstName |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
177 Last Name Attribute = lastName |
5412
2079e864ce51
spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents:
5077
diff
changeset
|
178 Email Attribute = mail |
992
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
179 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
180 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
|
181 |
6bad83d27fc1
Documentation: How to setup LDAP Filter when using Organisational Units.
Magnus Ericmats <magnus.ericmats@gmail.com>
parents:
3622
diff
changeset
|
182 Search settings |
6bad83d27fc1
Documentation: How to setup LDAP Filter when using Organisational Units.
Magnus Ericmats <magnus.ericmats@gmail.com>
parents:
3622
diff
changeset
|
183 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
|
184 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
|
185 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
|
186 |
992
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
187 .. _enable_ldap: |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
188 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
189 Enable LDAP : required |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
190 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
|
191 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
192 .. _ldap_host: |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
193 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
194 Host : required |
2916
f6685a62e455
Updated docs about LDAP failover server list option
Marcin Kuzminski <marcin@python-works.com>
parents:
2906
diff
changeset
|
195 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
|
196 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
|
197 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
198 .. _Port: |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
199 |
6331
949c843bb535
auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents:
6330
diff
changeset
|
200 Port : optional |
949c843bb535
auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents:
6330
diff
changeset
|
201 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
|
202 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
|
203 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
204 .. _ldap_account: |
707
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
205 |
992
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
206 Account : optional |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
207 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
|
208 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
|
209 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
|
210 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
211 .. _LDAP Password: |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
212 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
213 Password : optional |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
214 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
|
215 records. |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
216 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
217 .. _Enable LDAPS: |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
218 |
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
|
219 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
|
220 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
|
221 |
6331
949c843bb535
auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents:
6330
diff
changeset
|
222 PLAIN |
949c843bb535
auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents:
6330
diff
changeset
|
223 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
|
224 This will by default use `Port`_ 389. |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
225 |
6331
949c843bb535
auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents:
6330
diff
changeset
|
226 LDAPS |
949c843bb535
auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents:
6330
diff
changeset
|
227 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
|
228 Checks`_ configuration. |
949c843bb535
auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents:
6330
diff
changeset
|
229 This will by default use `Port`_ 636. |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
230 |
6331
949c843bb535
auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents:
6330
diff
changeset
|
231 START_TLS |
949c843bb535
auth: refactor ldap parameter handling - make it clear that port is optional
Mads Kiilerich <madski@unity3d.com>
parents:
6330
diff
changeset
|
232 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
|
233 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
|
234 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
|
235 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
236 .. _Certificate Checks: |
707
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
237 |
992
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
238 Certificate Checks : optional |
5435
60e04a21bf0f
docs: more consistent use of --
Mads Kiilerich <madski@unity3d.com>
parents:
5434
diff
changeset
|
239 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
|
240 `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
|
241 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
|
242 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
|
243 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
244 NEVER |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
245 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
|
246 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
247 ALLOW |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
248 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
|
249 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
|
250 session. |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
251 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
252 TRY |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
253 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
|
254 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
|
255 halts the session. |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
256 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
257 DEMAND |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
258 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
|
259 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
|
260 |
992
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
261 HARD |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
262 The same as DEMAND. |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
263 |
6330
7ce3897bacd0
auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents:
6153
diff
changeset
|
264 .. _Custom CA Certificates: |
7ce3897bacd0
auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents:
6153
diff
changeset
|
265 |
7ce3897bacd0
auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents:
6153
diff
changeset
|
266 Custom CA Certificates : optional |
7ce3897bacd0
auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents:
6153
diff
changeset
|
267 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
|
268 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
|
269 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
|
270 trusted by the system. |
7ce3897bacd0
auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents:
6153
diff
changeset
|
271 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
|
272 if using self-signed certificates. |
7ce3897bacd0
auth: make ldap OPT_X_TLS_CACERTDIR configurable
Mads Kiilerich <madski@unity3d.com>
parents:
6153
diff
changeset
|
273 |
992
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
274 .. _Base DN: |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
275 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
276 Base DN : required |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
277 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
|
278 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
|
279 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
280 .. _LDAP Filter: |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
281 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
282 LDAP Filter : optional |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
283 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
|
284 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
|
285 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
|
286 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
|
287 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
|
288 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
289 .. _LDAP Search Scope: |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
290 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
291 LDAP Search Scope : required |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
292 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
|
293 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
294 BASE |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
295 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
|
296 want. |
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 ONELEVEL |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
299 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
|
300 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
301 SUBTREE |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
302 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
|
303 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
|
304 location. |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
305 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
306 .. _Login Attribute: |
707
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
307 |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
308 Login Attribute : required |
992
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
309 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
|
310 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
|
311 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
|
312 "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
|
313 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
|
314 :: |
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 (&(LDAPFILTER)(uid=jsmith)) |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
317 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
318 .. _ldap_attr_firstname: |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
319 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
320 First Name Attribute : required |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
321 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
|
322 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
323 .. _ldap_attr_lastname: |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
324 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
325 Last Name Attribute : required |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
326 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
|
327 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
328 .. _ldap_attr_email: |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
329 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
330 Email Attribute : required |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
331 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
|
332 |
992
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
333 If all data are entered correctly, and python-ldap_ is properly installed |
4902 | 334 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
|
335 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
|
336 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
|
337 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
|
338 |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
339 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
|
340 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
|
341 will be saved there. |
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 Active Directory |
5575
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5534
diff
changeset
|
344 ^^^^^^^^^^^^^^^^ |
707
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
345 |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
346 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
|
347 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
|
348 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
|
349 Directory :: |
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 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
|
352 Login Attribute = sAMAccountName |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
353 First Name Attribute = givenName |
c03d16787b5c
Update documentation for LDAP settings (and add Active Directory information).
Thayne Harbaugh <thayne@fusionio.com>
parents:
968
diff
changeset
|
354 Last Name Attribute = sn |
5412
2079e864ce51
spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents:
5077
diff
changeset
|
355 Email Attribute = mail |
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 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
|
358 appropriately configured. |
777
aac24db58ce8
fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents:
775
diff
changeset
|
359 |
1467
da60cdb41969
doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents:
1448
diff
changeset
|
360 |
1657
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
361 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
|
362 -------------------------------------------- |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
363 |
4501
a68fc4abeda3
issue #7 remove obsolete configuration
domruf <dominikruf@gmail.com>
parents:
4448
diff
changeset
|
364 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
|
365 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
|
366 clients access the application. |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
367 |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
368 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
|
369 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
|
370 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
|
371 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
|
372 |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
373 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
|
374 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
|
375 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
|
376 |
1657
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
377 It's also possible for an administrator to create accounts and configure their |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
378 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
|
379 |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
380 Container-based authentication |
5575
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5534
diff
changeset
|
381 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
1657
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
382 |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
383 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
|
384 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
|
385 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
386 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
|
387 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
|
388 Kallithea. |
1657
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
389 |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
390 Proxy pass-through authentication |
5575
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5534
diff
changeset
|
391 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
1657
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
392 |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
393 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
|
394 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
|
395 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
|
396 |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
397 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
|
398 `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
|
399 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
|
400 ``X-Forwarded-User``. |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
401 |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
402 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
|
403 reverse-proxy setup with basic auth: |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
404 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
405 .. code-block:: apache |
1657
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
406 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
407 <Location /someprefix> |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
408 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
|
409 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
|
410 SetEnvIf X-Url-Scheme https HTTPS=1 |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
411 |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
412 AuthType Basic |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
413 AuthName "Kallithea authentication" |
4902 | 414 AuthUserFile /srv/kallithea/.htpasswd |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
415 Require valid-user |
1657
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
416 |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
417 RequestHeader unset X-Forwarded-User |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
418 |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
419 RewriteEngine On |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
420 RewriteCond %{LA-U:REMOTE_USER} (.+) |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
421 RewriteRule .* - [E=RU:%1] |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
422 RequestHeader set X-Forwarded-User %{RU}e |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
423 </Location> |
1657
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
424 |
5609
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
425 Setting metadata in container/reverse-proxy |
5815 | 426 """"""""""""""""""""""""""""""""""""""""""" |
5609
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
427 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
|
428 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
|
429 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
|
430 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
|
431 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
|
432 |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
433 .. 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
|
434 |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
435 <Location /someprefix> |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
436 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
|
437 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
|
438 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
|
439 |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
440 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
|
441 AuthType Kerberos |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
442 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
|
443 KrbMethodK5Passwd off |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
444 KrbVerifyKDC on |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
445 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
|
446 |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
447 PythonFixupHandler ldapmetadata |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
448 |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
449 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
|
450 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
|
451 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
|
452 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
|
453 </Location> |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
454 |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
455 .. 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
|
456 |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
457 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
|
458 import ldap |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
459 |
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
|
460 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
|
461 LDAP_USER = "" |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
462 LDAP_PASS = "" |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
463 LDAP_ROOT = "dc=mydomain,dc=com" |
5817 | 464 LDAP_FILTER = "sAMAccountName=%s" |
465 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
|
466 |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
467 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
|
468 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
|
469 # 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
|
470 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
|
471 else: |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
472 try: |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
473 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
|
474 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
|
475 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
|
476 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
|
477 else: |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
478 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
|
479 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
|
480 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
|
481 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
|
482 |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
483 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
|
484 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
|
485 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
|
486 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
|
487 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
|
488 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
|
489 |
ada6571a6d27
auth: let container authentication get email, first and last name from custom headers
domruf <dominikruf@gmail.com>
parents:
5594
diff
changeset
|
490 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
|
491 |
1657
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
492 .. note:: |
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
493 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
|
494 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
|
495 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
|
496 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
|
497 |
5413
22a3fa3c4254
docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
498 |
22a3fa3c4254
docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
499 Integration with issue trackers |
1838 | 500 ------------------------------- |
1657
d2a108366f8f
Added documentation for container-based and proxy pass-through authentication
Liad Shani <liadff@gmail.com>
parents:
1559
diff
changeset
|
501 |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
502 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
|
503 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
|
504 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
|
505 uncomment the following variables in the ini file:: |
1838 | 506 |
3943
a5bccf34c512
fixed docs error, should be issue_pat
Marcin Kuzminski <marcin@python-works.com>
parents:
3923
diff
changeset
|
507 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
|
508 issue_server_link = https://issues.example.com/{repo}/issue/{id} |
1838 | 509 issue_prefix = # |
510 | |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
511 ``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
|
512 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
|
513 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
|
514 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
515 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
|
516 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
517 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
|
518 ``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
|
519 ``{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
|
520 ``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
|
521 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
|
522 generate a URL in the format: |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
523 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
524 .. code-block:: html |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
525 |
5497
12b47803189f
cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents:
5496
diff
changeset
|
526 <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
|
527 |
4848
570a4e40f0bb
docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents:
4522
diff
changeset
|
528 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
|
529 the variables. For example:: |
570a4e40f0bb
docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents:
4522
diff
changeset
|
530 |
570a4e40f0bb
docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents:
4522
diff
changeset
|
531 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
|
532 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
|
533 issue_prefix_wiki = WIKI- |
570a4e40f0bb
docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents:
4522
diff
changeset
|
534 |
570a4e40f0bb
docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents:
4522
diff
changeset
|
535 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
|
536 such reference will be transformed into: |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
537 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
538 .. code-block:: html |
4848
570a4e40f0bb
docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents:
4522
diff
changeset
|
539 |
5497
12b47803189f
cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents:
5496
diff
changeset
|
540 <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
|
541 |
570a4e40f0bb
docs: improve issue tracker integration docs
Andrew Shadura <andrew@shadura.me>
parents:
4522
diff
changeset
|
542 |
1467
da60cdb41969
doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents:
1448
diff
changeset
|
543 Hook management |
da60cdb41969
doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents:
1448
diff
changeset
|
544 --------------- |
da60cdb41969
doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents:
1448
diff
changeset
|
545 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
546 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
|
547 To manage hooks, choose *Admin > Settings > Hooks*. |
1467
da60cdb41969
doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents:
1448
diff
changeset
|
548 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
549 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
|
550 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
551 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
|
552 ``<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
|
553 can be found in ``kallithea.lib.hooks``. |
1467
da60cdb41969
doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents:
1448
diff
changeset
|
554 |
da60cdb41969
doc update - hooks
Marcin Kuzminski <marcin@python-works.com>
parents:
1448
diff
changeset
|
555 |
2017
03a549b35c57
updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents:
1870
diff
changeset
|
556 Changing default encoding |
03a549b35c57
updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents:
1870
diff
changeset
|
557 ------------------------- |
03a549b35c57
updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents:
1870
diff
changeset
|
558 |
4914
95fe05b1e5f8
docs: better capitalisation
Andrew Shadura <andrew@shadura.me>
parents:
4902
diff
changeset
|
559 By default, Kallithea uses UTF-8 encoding. |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
560 This is configurable as ``default_encoding`` in the .ini file. |
4902 | 561 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
|
562 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
|
563 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
|
564 when there are encode/decode errors. |
03a549b35c57
updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents:
1870
diff
changeset
|
565 |
03a549b35c57
updated setup docs about encoding
Marcin Kuzminski <marcin@python-works.com>
parents:
1870
diff
changeset
|
566 |
4902 | 567 Celery configuration |
568 -------------------- | |
777
aac24db58ce8
fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents:
775
diff
changeset
|
569 |
4925
56cd202b777e
docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4915
diff
changeset
|
570 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
|
571 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
|
572 |
56cd202b777e
docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4915
diff
changeset
|
573 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
|
574 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
|
575 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
|
576 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
|
577 |
56cd202b777e
docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4915
diff
changeset
|
578 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
|
579 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
|
580 or Redis_. |
777
aac24db58ce8
fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents:
775
diff
changeset
|
581 |
4925
56cd202b777e
docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4915
diff
changeset
|
582 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
|
583 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
|
584 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
585 use_celery = true |
777
aac24db58ce8
fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents:
775
diff
changeset
|
586 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
587 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
|
588 |
56cd202b777e
docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4915
diff
changeset
|
589 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
|
590 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
|
591 `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
|
592 |
56cd202b777e
docs: move all instructions on Celery to Setup
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4915
diff
changeset
|
593 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
|
594 |
777
aac24db58ce8
fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents:
775
diff
changeset
|
595 paster celeryd <configfile.ini> |
aac24db58ce8
fixed cache problem,
Marcin Kuzminski <marcin@python-works.com>
parents:
775
diff
changeset
|
596 |
871
7f9e006aa26f
docs update for celeryd
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
597 .. note:: |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
598 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
|
599 user that Kallithea runs. |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
600 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
601 |
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
602 HTTPS support |
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
603 ------------- |
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
604 |
4448
8e26c46e9abe
https: introduce https_fixup config setting to enable the special https hacks
Mads Kiilerich <madski@unity3d.com>
parents:
4192
diff
changeset
|
605 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
|
606 |
8e26c46e9abe
https: introduce https_fixup config setting to enable the special https hacks
Mads Kiilerich <madski@unity3d.com>
parents:
4192
diff
changeset
|
607 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
|
608 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
|
609 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
610 - 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
|
611 ``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
|
612 (default ``http``). |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
613 - 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
|
614 - 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
|
615 |
871
7f9e006aa26f
docs update for celeryd
Marcin Kuzminski <marcin@python-works.com>
parents:
845
diff
changeset
|
616 |
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
617 Nginx virtual host example |
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
618 -------------------------- |
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
619 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
620 Sample config for Nginx using proxy: |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
621 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
622 .. code-block:: nginx |
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
623 |
4902 | 624 upstream kallithea { |
1745
456e1e3ce4eb
fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents:
1657
diff
changeset
|
625 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
|
626 # 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
|
627 #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
|
628 #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
|
629 } |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
630 |
3850
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
631 ## gist alias |
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
632 server { |
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
633 listen 443; |
5497
12b47803189f
cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents:
5496
diff
changeset
|
634 server_name gist.example.com; |
3850
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
635 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
|
636 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
|
637 |
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
638 ssl on; |
4182
05cabd91f7c3
Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4180
diff
changeset
|
639 ssl_certificate gist.your.kallithea.server.crt; |
05cabd91f7c3
Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4180
diff
changeset
|
640 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
|
641 |
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
642 ssl_session_timeout 5m; |
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
643 |
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
644 ssl_protocols SSLv3 TLSv1; |
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
645 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
|
646 ssl_prefer_server_ciphers on; |
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
647 |
5497
12b47803189f
cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents:
5496
diff
changeset
|
648 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
|
649 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
|
650 } |
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
651 |
1092
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
652 server { |
3243
c759c0912642
switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents:
3224
diff
changeset
|
653 listen 443; |
5497
12b47803189f
cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents:
5496
diff
changeset
|
654 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
|
655 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
|
656 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
|
657 |
3243
c759c0912642
switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents:
3224
diff
changeset
|
658 ssl on; |
4182
05cabd91f7c3
Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4180
diff
changeset
|
659 ssl_certificate your.kallithea.server.crt; |
05cabd91f7c3
Change example URL
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4180
diff
changeset
|
660 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
|
661 |
c759c0912642
switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents:
3224
diff
changeset
|
662 ssl_session_timeout 5m; |
c759c0912642
switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents:
3224
diff
changeset
|
663 |
c759c0912642
switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents:
3224
diff
changeset
|
664 ssl_protocols SSLv3 TLSv1; |
c759c0912642
switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents:
3224
diff
changeset
|
665 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
|
666 ssl_prefer_server_ciphers on; |
c759c0912642
switch to SSL configuration example on nginx
Marcin Kuzminski <marcin@python-works.com>
parents:
3224
diff
changeset
|
667 |
3850
7a4df261a375
added alias configuration option for gists.
Marcin Kuzminski <marcin@python-works.com>
parents:
3801
diff
changeset
|
668 ## 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
|
669 ## 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
|
670 #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
|
671 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
|
672 location / { |
4902 | 673 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
|
674 } |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
675 |
4902 | 676 location @kallithea { |
5496
2b2216e8af36
docs: update example output and example server configs
Søren Løvborg <sorenl@unity3d.com>
parents:
5435
diff
changeset
|
677 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
|
678 } |
456e1e3ce4eb
fixes #305 User guide suggests sub-optimal nginx configuration
Marcin Kuzminski <marcin@python-works.com>
parents:
1657
diff
changeset
|
679 |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
680 } |
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
681 |
1092
8af52e1224ff
merge docs in beta with those corrected by Jason Harris
Marcin Kuzminski <marcin@python-works.com>
parents:
1062
diff
changeset
|
682 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
|
683 pushes or large pushes:: |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
684 |
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
685 proxy_redirect off; |
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
686 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
|
687 ## 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
|
688 #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
|
689 #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
|
690 proxy_set_header X-Url-Scheme $scheme; |
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
691 proxy_set_header X-Host $http_host; |
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
692 proxy_set_header X-Real-IP $remote_addr; |
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
693 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
|
694 proxy_set_header Proxy-host $proxy_host; |
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
695 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
|
696 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
|
697 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
|
698 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
|
699 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
|
700 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
|
701 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
|
702 large_client_header_buffers 8 64k; |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
703 |
881
68aaa0aca0d2
Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents:
871
diff
changeset
|
704 |
1558
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
705 Apache virtual host reverse proxy example |
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
706 ----------------------------------------- |
881
68aaa0aca0d2
Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents:
871
diff
changeset
|
707 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
708 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
|
709 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
710 .. code-block:: apache |
881
68aaa0aca0d2
Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents:
871
diff
changeset
|
711 |
929 | 712 <VirtualHost *:80> |
5497
12b47803189f
cleanup: use example.com for tests and examples
Søren Løvborg <sorenl@unity3d.com>
parents:
5496
diff
changeset
|
713 ServerName kallithea.example.com |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
714 |
929 | 715 <Proxy *> |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
716 # For Apache 2.4 and later: |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
717 Require all granted |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
718 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
719 # 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
|
720 # Order allow,deny |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
721 # Allow from all |
929 | 722 </Proxy> |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
723 |
929 | 724 #important ! |
6339
8845ece50d51
docs: remove some references to Pylons
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6335
diff
changeset
|
725 #Directive to properly generate url (clone url) for Kallithea |
929 | 726 ProxyPreserveHost On |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
727 |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
728 #kallithea instance |
929 | 729 ProxyPass / http://127.0.0.1:5000/ |
730 ProxyPassReverse / http://127.0.0.1:5000/ | |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
731 |
929 | 732 #to enable https use line below |
733 #SetEnvIf X-Url-Scheme https HTTPS=1 | |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
734 </VirtualHost> |
881
68aaa0aca0d2
Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents:
871
diff
changeset
|
735 |
68aaa0aca0d2
Updated docs, added apache proxy example config
Marcin Kuzminski <marcin@python-works.com>
parents:
871
diff
changeset
|
736 Additional tutorial |
4915
6892b0515af9
docs: replace a dead link to the pylons cookbook
Andrew Shadura <andrew@shadura.me>
parents:
4914
diff
changeset
|
737 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
|
738 |
707
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
739 |
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
740 Apache as subdirectory |
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
741 ---------------------- |
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
742 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
743 Apache subdirectory part: |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
744 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
745 .. code-block:: apache |
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
746 |
1226
f17fdbe86ab9
update docs for setup
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
747 <Location /<someprefix> > |
f17fdbe86ab9
update docs for setup
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
748 ProxyPass http://127.0.0.1:5000/<someprefix> |
f17fdbe86ab9
update docs for setup
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
749 ProxyPassReverse http://127.0.0.1:5000/<someprefix> |
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
750 SetEnvIf X-Url-Scheme https HTTPS=1 |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
751 </Location> |
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
752 |
1392
00b8fca6886c
fixes issue #206
Marcin Kuzminski <marcin@python-works.com>
parents:
1386
diff
changeset
|
753 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
|
754 into ``[app:main]`` section of your .ini file:: |
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
755 |
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
756 filter-with = proxy-prefix |
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
757 |
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
758 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
|
759 |
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
760 [filter:proxy-prefix] |
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
761 use = egg:PasteDeploy#prefix |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
762 prefix = /<someprefix> |
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
992
diff
changeset
|
763 |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
764 then change ``<someprefix>`` into your chosen prefix |
1226
f17fdbe86ab9
update docs for setup
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
765 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5426
diff
changeset
|
766 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
767 Apache with mod_wsgi |
1386
5a31d387f347
Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents:
1309
diff
changeset
|
768 -------------------- |
5a31d387f347
Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents:
1309
diff
changeset
|
769 |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
770 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
|
771 that, you'll need to: |
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
772 |
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
773 - 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
|
774 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
|
775 |
1558
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
776 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
|
777 |
1558
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
778 - Enable mod_wsgi:: |
1559
a9fef2e6c1ff
Syntax correction on the recently changed documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1558
diff
changeset
|
779 |
1558
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
780 a2enmod wsgi |
1559
a9fef2e6c1ff
Syntax correction on the recently changed documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1558
diff
changeset
|
781 |
5789
8c479b274e03
docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents:
5788
diff
changeset
|
782 - 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
|
783 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
|
784 processes:: |
8c479b274e03
docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents:
5788
diff
changeset
|
785 |
8c479b274e03
docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents:
5788
diff
changeset
|
786 WSGIRestrictEmbedded On |
8c479b274e03
docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents:
5788
diff
changeset
|
787 |
1558
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
788 - 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
|
789 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
|
790 and its Python Virtual Environment. |
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4925
diff
changeset
|
791 - 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
|
792 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
|
793 correctly specified. |
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
794 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
795 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
|
796 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
797 .. code-block:: apache |
1558
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
798 |
6153
d6942b2b421c
config: clarify that we only recommend and support single threaded operation
Mads Kiilerich <madski@unity3d.com>
parents:
5880
diff
changeset
|
799 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
|
800 python-home=/srv/kallithea/venv |
8c479b274e03
docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents:
5788
diff
changeset
|
801 WSGIProcessGroup kallithea |
4902 | 802 WSGIScriptAlias / /srv/kallithea/dispatch.wsgi |
2076
77d215d6121f
docs on apache WSGI update
Marcin Kuzminski <marcin@python-works.com>
parents:
2017
diff
changeset
|
803 WSGIPassAuthorization On |
1386
5a31d387f347
Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents:
1309
diff
changeset
|
804 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
805 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
|
806 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
807 .. code-block:: apache |
4902 | 808 |
6153
d6942b2b421c
config: clarify that we only recommend and support single threaded operation
Mads Kiilerich <madski@unity3d.com>
parents:
5880
diff
changeset
|
809 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
|
810 WSGIProcessGroup kallithea |
4902 | 811 WSGIScriptAlias / /srv/kallithea/dispatch.wsgi |
812 WSGIPassAuthorization On | |
813 | |
5789
8c479b274e03
docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents:
5788
diff
changeset
|
814 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
|
815 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
|
816 directory owned by a different user, use the user and group options to |
5791 | 817 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
|
818 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
819 Example WSGI dispatch script: |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
820 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
821 .. code-block:: python |
707
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
822 |
1386
5a31d387f347
Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents:
1309
diff
changeset
|
823 import os |
5a31d387f347
Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents:
1309
diff
changeset
|
824 os.environ["HGENCODING"] = "UTF-8" |
4902 | 825 os.environ['PYTHON_EGG_CACHE'] = '/srv/kallithea/.egg-cache' |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
826 |
5832 | 827 # sometimes it's needed to set the current dir |
4902 | 828 os.chdir('/srv/kallithea/') |
1558
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
829 |
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
830 import site |
5592
57bae44fd22e
docs: consistently use venv instead of pyenv
Mads Kiilerich <madski@unity3d.com>
parents:
5497
diff
changeset
|
831 site.addsitedir("/srv/kallithea/venv/lib/python2.7/site-packages") |
3224
8b8edfc25856
whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2916
diff
changeset
|
832 |
5789
8c479b274e03
docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents:
5788
diff
changeset
|
833 ini = '/srv/kallithea/my.ini' |
1386
5a31d387f347
Added example wsgi config into docs
Marcin Kuzminski <marcin@python-works.com>
parents:
1309
diff
changeset
|
834 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
|
835 fileConfig(ini) |
8c479b274e03
docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents:
5788
diff
changeset
|
836 from paste.deploy import loadapp |
8c479b274e03
docs: improve mod_wsgi documentation (Issue #203)
Mads Kiilerich <madski@unity3d.com>
parents:
5788
diff
changeset
|
837 application = loadapp('config:' + ini) |
4902 | 838 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
839 Or using proper virtualenv activation: |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
840 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
841 .. code-block:: python |
4902 | 842 |
843 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
|
844 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
|
845 |
4902 | 846 import os |
847 os.environ['HOME'] = '/srv/kallithea' | |
848 | |
849 ini = '/srv/kallithea/kallithea.ini' | |
850 from paste.script.util.logging_config import fileConfig | |
851 fileConfig(ini) | |
852 from paste.deploy import loadapp | |
853 application = loadapp('config:' + ini) | |
1558
662173ba1846
Improvements to mod_wsgi setup documentation.
Augusto Herrmann <augusto.herrmann@planejamento.gov.br>
parents:
1467
diff
changeset
|
854 |
707
1105531ae572
docs update, added ldap section, added troubleshooting section
Marcin Kuzminski <marcin@python-works.com>
parents:
683
diff
changeset
|
855 |
591 | 856 Other configuration files |
857 ------------------------- | |
858 | |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
859 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
|
860 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
|
861 |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
862 .. __: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ . |
591 | 863 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5426
diff
changeset
|
864 |
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
865 .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
866 .. _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
|
867 .. _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
|
868 .. _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
|
869 .. _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
|
870 .. _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
|
871 .. _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
|
872 .. _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
|
873 .. _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
|
874 .. _PublishingRepositories: https://www.mercurial-scm.org/wiki/PublishingRepositories |