Mercurial > kallithea
annotate docs/installation_iis.rst @ 5623:2e977722f349
db: drop unused settings.permission_longname field
author | Mads Kiilerich <madski@unity3d.com> |
---|---|
date | Tue, 05 Jan 2016 16:30:12 +0100 |
parents | ed2fb6e84a02 |
children | 5a47ce11427c |
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 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
12 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
|
13 a secure connection, e.g. using TLS. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
14 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
15 |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
16 Prerequisites |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
17 ------------- |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
18 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
19 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
|
20 ISAPI-WSGI bridge module, e.g. isapi-wsgi. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
21 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
22 |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
23 Installation |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
24 ------------ |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
25 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
26 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
|
27 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
|
28 own virtual folder will be noted where appropriate. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
29 |
5413
22a3fa3c4254
docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents:
4554
diff
changeset
|
30 Application pool |
5575
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5502
diff
changeset
|
31 ^^^^^^^^^^^^^^^^ |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
32 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
33 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
|
34 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
|
35 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
36 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
|
37 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
|
38 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
|
39 to run on the website and neither will Kallithea. |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
40 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
41 .. note:: |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
42 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5413
diff
changeset
|
43 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
|
44 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
|
45 |
5413
22a3fa3c4254
docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents:
4554
diff
changeset
|
46 ISAPI handler |
5575
ed2fb6e84a02
docs: use consistent style for section titles
Mads Kiilerich <madski@unity3d.com>
parents:
5502
diff
changeset
|
47 ^^^^^^^^^^^^^ |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
48 |
4554
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
49 The ISAPI handler can be generated using:: |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
50 |
4554
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
51 paster install-iis my.ini --root=/ |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
52 |
4554
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
53 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
|
54 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
|
55 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
|
56 that ISAPI-WSGI is made:: |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
57 |
5502
ae9ab4c92d46
setup: explicitly use python2 in examples in the documentation
Mads Kiilerich <madski@unity3d.com>
parents:
5433
diff
changeset
|
58 python2 dispatch.py install |
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 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
|
61 ``_dispatch.dll``, and installing a script map handler into IIS for the |
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
62 ``--root`` specified above pointing to ``_dispatch.dll``. |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
63 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
64 The ISAPI handler is registered to all file extensions, so it will automatically |
4554
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
65 be the one handling all requests to the specified root. When the website starts |
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
66 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
|
67 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
|
68 site will be processed through this logic henceforth. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
69 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
70 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
|
71 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
72 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
73 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
|
74 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
|
75 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
76 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
|
77 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
|
78 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
|
79 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
|
80 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
|
81 Finally, save the changes on this page. |
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 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
|
84 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
|
85 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
|
86 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
|
87 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
|
88 external account*. Finally, save the changes. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
89 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
90 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
|
91 Windows authentication. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
92 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
93 |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
94 Troubleshooting |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
95 --------------- |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
96 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
97 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
|
98 in Kallithea (or Kallithea's WSGI/paster middleware). Consequently, two |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
99 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
|
100 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
|
101 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
|
102 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
103 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
|
104 type the following in a console window:: |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
105 |
5502
ae9ab4c92d46
setup: explicitly use python2 in examples in the documentation
Mads Kiilerich <madski@unity3d.com>
parents:
5433
diff
changeset
|
106 python2 -m win32traceutil |
4500
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 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
|
109 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
|
110 traces, making it a lot easier to identify issues. |