Mercurial > kallithea
annotate docs/installation_iis.rst @ 6464:d7d1e0a3850a
model: inline calls to BaseModel._get_repo
author | Søren Løvborg <sorenl@unity3d.com> |
---|---|
date | Wed, 18 Jan 2017 16:56:26 +0100 |
parents | 1cc0c0aed87a |
children | 2c3d30095d5e |
rev | line source |
---|---|
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
1 .. _installation_iis: |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
2 |
5413
22a3fa3c4254
docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents:
4554
diff
changeset
|
3 ===================================================================== |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
4 Installing Kallithea on Microsoft Internet Information Services (IIS) |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
5 ===================================================================== |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
6 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
7 The following is documented using IIS 7/8 terminology. There should be nothing |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
8 preventing you from applying this on IIS 6 well. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
9 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
10 .. note:: |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
11 |
5788
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
12 Installing Kallithea under IIS can enable Single Sign-On to the Kallithea |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
13 web interface from web browsers that can authenticate to the web server. |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
14 (As an alternative to IIS, SSO is also possible with for example Apache and |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
15 mod_sspi.) |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
16 |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
17 Mercurial and Git do however by default not support SSO on the client side |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
18 and will still require some other kind of authentication. |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
19 (An extension like hgssoauthentication_ might solve that.) |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
20 |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
21 .. note:: |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
22 |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
23 For the best security, it is strongly recommended to only host the site over |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
24 a secure connection, e.g. using TLS. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
25 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
26 |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
27 Prerequisites |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
28 ------------- |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
29 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
30 Apart from the normal requirements for Kallithea, it is also necessary to get an |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
31 ISAPI-WSGI bridge module, e.g. isapi-wsgi. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
32 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
33 |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
34 Installation |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
35 ------------ |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
36 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
37 The following assumes that your Kallithea is at ``c:\inetpub\kallithea``, and |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
38 will be served from the root of its own website. The changes to serve it in its |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
39 own virtual folder will be noted where appropriate. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
40 |
5413
22a3fa3c4254
docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents:
4554
diff
changeset
|
41 Application pool |
5575
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5502
diff
changeset
|
42 ^^^^^^^^^^^^^^^^ |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
43 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
44 Make sure that there is a unique application pool for the Kallithea application |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
45 with an identity that has read access to the Kallithea distribution. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
46 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
47 The application pool does not need to be able to run any managed code. If you |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
48 are using a 32-bit Python installation, then you must enable 32-bit program in |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
49 the advanced settings for the application pool; otherwise Python will not be able |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
50 to run on the website and neither will Kallithea. |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
51 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
52 .. note:: |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
53 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
54 The application pool can be the same as an existing application pool, |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
55 as long as the Kallithea requirements are met by the existing pool. |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
56 |
5413
22a3fa3c4254
docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents:
4554
diff
changeset
|
57 ISAPI handler |
5575
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5502
diff
changeset
|
58 ^^^^^^^^^^^^^ |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
59 |
4554
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
60 The ISAPI handler can be generated using:: |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
61 |
5788
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
62 paster install-iis my.ini --virtualdir=/ |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
63 |
4554
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
64 This will generate a ``dispatch.py`` file in the current directory that contains |
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
65 the necessary components to finalize an installation into IIS. Once this file |
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
66 has been generated, it is necessary to run the following command due to the way |
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
67 that ISAPI-WSGI is made:: |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
68 |
5502
ae9ab4c92d46
setup: explicitly use python2 in examples in the documentation
Mads Kiilerich <madski@unity3d.com>
parents:
5433
diff
changeset
|
69 python2 dispatch.py install |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
70 |
4554
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
71 This accomplishes two things: generating an ISAPI compliant DLL file, |
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
72 ``_dispatch.dll``, and installing a script map handler into IIS for the |
5788
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
73 ``--virtualdir`` specified above pointing to ``_dispatch.dll``. |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
74 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
75 The ISAPI handler is registered to all file extensions, so it will automatically |
5788
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
76 be the one handling all requests to the specified virtual directory. When the website starts |
4554
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
77 the ISAPI handler, it will start a thread pool managed wrapper around the paster |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
78 middleware WSGI handler that Kallithea runs within and each HTTP request to the |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
79 site will be processed through this logic henceforth. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
80 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
81 Authentication with Kallithea using IIS authentication modules |
5575
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5502
diff
changeset
|
82 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
83 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
84 The recommended way to handle authentication with Kallithea using IIS is to let |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
85 IIS handle all the authentication and just pass it to Kallithea. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
86 |
5788
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
87 .. note:: |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
88 |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
89 As an alternative without SSO, you can also use LDAP authentication with |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
90 Active Directory, see :ref:`ldap-setup`. |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
91 |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
92 To move responsibility into IIS from Kallithea, we need to configure Kallithea |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
93 to let external systems handle authentication and then let Kallithea create the |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
94 user automatically. To do this, access the administration's authentication page |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
95 and enable the ``kallithea.lib.auth_modules.auth_container`` plugin. Once it is |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
96 added, enable it with the ``REMOTE_USER`` header and check *Clean username*. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
97 Finally, save the changes on this page. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
98 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
99 Switch to the administration's permissions page and disable anonymous access, |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
100 otherwise Kallithea will not attempt to use the authenticated user name. By |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
101 default, Kallithea will populate the list of users lazily as they log in. Either |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
102 disable external auth account activation and ensure that you pre-populate the |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
103 user database with an external tool, or set it to *Automatic activation of |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
104 external account*. Finally, save the changes. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
105 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
106 The last necessary step is to enable the relevant authentication in IIS, e.g. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
107 Windows authentication. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
108 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
109 |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
110 Troubleshooting |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
111 --------------- |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
112 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
113 Typically, any issues in this setup will either be entirely in IIS or entirely |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
114 in Kallithea (or Kallithea's WSGI/paster middleware). Consequently, two |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
115 different options for finding issues exist: IIS' failed request tracking which |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
116 is great at finding issues until they exist inside Kallithea, at which point the |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
117 ISAPI-WSGI wrapper above uses ``win32traceutil``, which is part of ``pywin32``. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
118 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
119 In order to dump output from WSGI using ``win32traceutil`` it is sufficient to |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
120 type the following in a console window:: |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
121 |
5502
ae9ab4c92d46
setup: explicitly use python2 in examples in the documentation
Mads Kiilerich <madski@unity3d.com>
parents:
5433
diff
changeset
|
122 python2 -m win32traceutil |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
123 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
124 and any exceptions occurring in the WSGI layer and below (i.e. in the Kallithea |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
125 application itself) that are uncaught, will be printed here complete with stack |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
126 traces, making it a lot easier to identify issues. |
5788
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
127 |
2d89d49c30e8
docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents:
5502
diff
changeset
|
128 |
5825 | 129 .. _hgssoauthentication: https://bitbucket.org/domruf/hgssoauthentication |