Mercurial > kallithea

annotate docs/installation_iis.rst @ 8899:af20f57282ff i18n

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge stable
author Mads Kiilerich <mads@kiilerich.com>
date Sun, 30 May 2021 01:34:48 +0200
parents 01aca0a4f876
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
8209
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 7626
diff changeset
3 .. warning:: This section is outdated and needs updating for Python 3.
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 7626
diff changeset
4
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 4554
diff changeset
5 =====================================================================
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
6 Installing Kallithea on Microsoft Internet Information Services (IIS)
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
7 =====================================================================
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
8
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
9 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
10 preventing you from applying this on IIS 6 well.
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
11
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
12 .. note::
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
13
5788
2d89d49c30e8 docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5502
diff changeset
14 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
15 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
16 (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
17 mod_sspi.)
2d89d49c30e8 docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5502
diff changeset
18
2d89d49c30e8 docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5502
diff changeset
19 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
20 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
21 (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
22
2d89d49c30e8 docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5502
diff changeset
23 .. note::
2d89d49c30e8 docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5502
diff changeset
24
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
25 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
26 a secure connection, e.g. using TLS.
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
27
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5425
diff changeset
28
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
29 Prerequisites
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
30 -------------
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
31
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
32 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
33 ISAPI-WSGI bridge module, e.g. isapi-wsgi.
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
34
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5425
diff changeset
35
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
36 Installation
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
37 ------------
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
38
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
39 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
40 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
41 own virtual folder will be noted where appropriate.
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
42
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 4554
diff changeset
43 Application pool
5575
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5502
diff changeset
44 ^^^^^^^^^^^^^^^^
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
45
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
46 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
47 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
48
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
49 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
50 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
51 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
52 to run on the website and neither will Kallithea.
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
53
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
54 .. note::
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
55
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5413
diff changeset
56 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
57 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
58
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 4554
diff changeset
59 ISAPI handler
5575
ed2fb6e84a02 docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents: 5502
diff changeset
60 ^^^^^^^^^^^^^
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
61
4554
2dad9708c89f paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents: 4500
diff changeset
62 The ISAPI handler can be generated using::
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
63
7413
9de61c5b8694 cli: convert 'gearbox install-iis' into 'kallithea-cli iis-install'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 6554
diff changeset
64 kallithea-cli iis-install -c my.ini --virtualdir=/
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
65
4554
2dad9708c89f paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents: 4500
diff changeset
66 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
67 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
68 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
69 that ISAPI-WSGI is made::
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
70
8209
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 7626
diff changeset
71 python3 dispatch.py install
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
72
4554
2dad9708c89f paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents: 4500
diff changeset
73 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
74 ``_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
75 ``--virtualdir`` specified above pointing to ``_dispatch.dll``.
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
76
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
77 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
78 be the one handling all requests to the specified virtual directory. When the website starts
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 5825
diff changeset
79 the ISAPI handler, it will start a thread pool managed wrapper around the
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
80 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
81 site will be processed through this logic henceforth.
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
82
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
83 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
84 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
85
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
86 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
87 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
88
5788
2d89d49c30e8 docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5502
diff changeset
89 .. note::
2d89d49c30e8 docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5502
diff changeset
90
2d89d49c30e8 docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5502
diff changeset
91 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
92 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
93
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
94 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
95 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
96 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
97 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
98 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
99 Finally, save the changes on this page.
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
100
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
101 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
102 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
103 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
104 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
105 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
106 external account*. Finally, save the changes.
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
107
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
108 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
109 Windows authentication.
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
110
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5425
diff changeset
111
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
112 Troubleshooting
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
113 ---------------
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
114
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
115 Typically, any issues in this setup will either be entirely in IIS or entirely
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 5825
diff changeset
116 in Kallithea (or Kallithea's WSGI middleware). Consequently, two
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
117 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
118 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
119 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
120
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
121 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
122 type the following in a console window::
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
123
8209
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 7626
diff changeset
124 python3 -m win32traceutil
4500
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
125
e69d34136be5 docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff changeset
126 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
127 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
128 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
129
2d89d49c30e8 docs: add notes about IIS, Windows Authentication and Mercurial
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5502
diff changeset
130
5825
1cc0c0aed87a spelling: authentication
timeless@gmail.com
parents: 5792
diff changeset
131 .. _hgssoauthentication: https://bitbucket.org/domruf/hgssoauthentication