Mercurial > kallithea
comparison docs/installation_iis.rst @ 4500:e69d34136be5
docs: describe installation under IIS
author | Henrik Stuart <hg@hstuart.dk> |
---|---|
date | Sun, 31 Aug 2014 12:11:50 +0200 |
parents | |
children | 2dad9708c89f |
comparison
equal
deleted
inserted
replaced
4499:bbf4118f6e0f | 4500:e69d34136be5 |
---|---|
1 .. _installation_iis: | |
2 | |
3 Installing Kallithea on Microsoft Internet Information Services (IIS) | |
4 ===================================================================== | |
5 | |
6 The following is documented using IIS 7/8 terminology. There should be nothing | |
7 preventing you from applying this on IIS 6 well. | |
8 | |
9 .. note:: | |
10 | |
11 For the best security, it is strongly recommended to only host the site over | |
12 a secure connection, e.g. using TLS. | |
13 | |
14 Prerequisites | |
15 ------------- | |
16 | |
17 Apart from the normal requirements for Kallithea, it is also necessary to get an | |
18 ISAPI-WSGI bridge module, e.g. isapi-wsgi. | |
19 | |
20 Installation | |
21 ------------ | |
22 | |
23 The following will assume that your Kallithea is at ``c:\inetpub\kallithea`` and | |
24 will be served from the root of its own website. The changes to serve it in its | |
25 own virtual folder will be noted where appropriate. | |
26 | |
27 Application Pool | |
28 ................ | |
29 | |
30 Make sure that there is a unique application pool for the Kallithea application | |
31 with an identity that has read access to the Kallithea distribution. | |
32 | |
33 The application pool does not need to be able to run any managed code. If you | |
34 are using a 32-bit Python installation, then you must enable 32 bit program in | |
35 the advanced settings for the application pool otherwise Python will not be able | |
36 to run on the website and consequently, Kallithea will not be able to run. | |
37 | |
38 .. note:: | |
39 | |
40 The application pool can be the same as an existing application pool as long | |
41 as the requirements to Kallithea are enabled by the existing application | |
42 pool. | |
43 | |
44 ISAPI Handler | |
45 ............. | |
46 | |
47 The ISAPI handler needs to be generated from a custom file. Imagining that the | |
48 Kallithea installation is in ``c:\inetpub\kallithea``, we would have a file in | |
49 the same directory called, e.g. ``dispatch.py`` with the following contents:: | |
50 | |
51 import sys | |
52 | |
53 if hasattr(sys, "isapidllhandle"): | |
54 import win32traceutil | |
55 | |
56 import isapi_wsgi | |
57 | |
58 def __ExtensionFactory__(): | |
59 from paste.deploy import loadapp | |
60 from paste.script.util.logging_config import fileConfig | |
61 fileConfig('c:\\inetpub\\kallithea\\production.ini') | |
62 application = loadapp('config:c:\\inetpub\\kallithea\\production.ini') | |
63 | |
64 def app(environ, start_response): | |
65 user = environ.get('REMOTE_USER', None) | |
66 if user is not None: | |
67 os.environ['REMOTE_USER'] = user | |
68 return application(environ, start_response) | |
69 | |
70 return isapi_wsgi.ISAPIThreadPoolHandler(app) | |
71 | |
72 if __name__=='__main__': | |
73 from isapi.install import * | |
74 params = ISAPIParameters() | |
75 sm = [ScriptMapParams(Extension="*", Flags=0)] | |
76 vd = VirtualDirParameters(Name="/", | |
77 Description = "ISAPI-WSGI Echo Test", | |
78 ScriptMaps = sm, | |
79 ScriptMapUpdate = "replace") | |
80 params.VirtualDirs = [vd] | |
81 HandleCommandLine(params) | |
82 | |
83 This script has two parts: First, when run directly using Python, it will | |
84 install a script map ISAPI handler into the root application of the default | |
85 website, and secondly it will be called from the ISAPI handler when invoked | |
86 from the website. | |
87 | |
88 The ISAPI handler is registered to all file extensions, so it will automatically | |
89 be the one handling all requests to the website. When the website starts the | |
90 ISAPI handler, it will start a thread pool managed wrapper around the paster | |
91 middleware WSGI handler that Kallithea runs within and each HTTP request to the | |
92 site will be processed through this logic henceforth. | |
93 | |
94 Authentication with Kallithea using IIS authentication modules | |
95 .............................................................. | |
96 | |
97 The recommended way to handle authentication with Kallithea using IIS is to let | |
98 IIS handle all the authentication and just pass it to Kallithea. | |
99 | |
100 To move responsibility into IIS from Kallithea, we need to configure Kallithea | |
101 to let external systems handle authentication and then let Kallithea create the | |
102 user automatically. To do this, access the administration's authentication page | |
103 and enable the ``kallithea.lib.auth_modules.auth_container`` plugin. Once it is | |
104 added, enable it with the ``REMOTE_USER`` header and check *Clean username*. | |
105 Finally, save the changes on this page. | |
106 | |
107 Switch to the administration's permissions page and disable anonymous access, | |
108 otherwise Kallithea will not attempt to use the authenticated user name. By | |
109 default, Kallithea will populate the list of users lazily as they log in. Either | |
110 disable external auth account activation and ensure that you pre-populate the | |
111 user database with an external tool, or set it to *Automatic activation of | |
112 external account*. Finally, save the changes. | |
113 | |
114 The last necessary step is to enable the relevant authentication in IIS, e.g. | |
115 Windows authentication. | |
116 | |
117 Troubleshooting | |
118 --------------- | |
119 | |
120 Typically, any issues in this setup will either be entirely in IIS or entirely | |
121 in Kallithea (or Kallithea's WSGI/paster middleware). Consequently, two | |
122 different options for finding issues exist: IIS' failed request tracking which | |
123 is great at finding issues until they exist inside Kallithea, at which point the | |
124 ISAPI-WSGI wrapper above uses ``win32traceutil``, which is part of ``pywin32``. | |
125 | |
126 In order to dump output from WSGI using ``win32traceutil`` it is sufficient to | |
127 type the following in a console window:: | |
128 | |
129 python -m win32traceutil | |
130 | |
131 and any exceptions occurring in the WSGI layer and below (i.e. in the Kallithea | |
132 application itself) that are uncaught, will be printed here complete with stack | |
133 traces, making it a lot easier to identify issues. |