Mercurial > kallithea
annotate docs/installation_iis.rst @ 4516:b3f12c354e87
javascript: remove nice trailing comma to please IE8 (Issue #39)
author | Mads Kiilerich <madski@unity3d.com> |
---|---|
date | Wed, 24 Sep 2014 14:24:40 +0200 |
parents | e69d34136be5 |
children | 2dad9708c89f |
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 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
3 Installing Kallithea on Microsoft Internet Information Services (IIS) |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
4 ===================================================================== |
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 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
|
7 preventing you from applying this on IIS 6 well. |
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 .. note:: |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
10 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
11 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
|
12 a secure connection, e.g. using TLS. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
13 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
14 Prerequisites |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
15 ------------- |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
16 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
17 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
|
18 ISAPI-WSGI bridge module, e.g. isapi-wsgi. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
19 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
20 Installation |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
21 ------------ |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
22 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
23 The following will assume that your Kallithea is at ``c:\inetpub\kallithea`` and |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
24 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
|
25 own virtual folder will be noted where appropriate. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
26 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
27 Application Pool |
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 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
|
31 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
|
32 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
33 The application pool does not need to be able to run any managed code. If you |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
34 are using a 32-bit Python installation, then you must enable 32 bit program in |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
35 the advanced settings for the application pool otherwise Python will not be able |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
36 to run on the website and consequently, Kallithea will not be able to run. |
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 .. note:: |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
39 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
40 The application pool can be the same as an existing application pool as long |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
41 as the requirements to Kallithea are enabled by the existing application |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
42 pool. |
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 ISAPI Handler |
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 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
47 The ISAPI handler needs to be generated from a custom file. Imagining that the |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
48 Kallithea installation is in ``c:\inetpub\kallithea``, we would have a file in |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
49 the same directory called, e.g. ``dispatch.py`` with the following contents:: |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
50 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
51 import sys |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
52 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
53 if hasattr(sys, "isapidllhandle"): |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
54 import win32traceutil |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
55 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
56 import isapi_wsgi |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
57 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
58 def __ExtensionFactory__(): |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
59 from paste.deploy import loadapp |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
60 from paste.script.util.logging_config import fileConfig |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
61 fileConfig('c:\\inetpub\\kallithea\\production.ini') |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
62 application = loadapp('config:c:\\inetpub\\kallithea\\production.ini') |
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 def app(environ, start_response): |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
65 user = environ.get('REMOTE_USER', None) |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
66 if user is not None: |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
67 os.environ['REMOTE_USER'] = user |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
68 return application(environ, start_response) |
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 return isapi_wsgi.ISAPIThreadPoolHandler(app) |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
71 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
72 if __name__=='__main__': |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
73 from isapi.install import * |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
74 params = ISAPIParameters() |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
75 sm = [ScriptMapParams(Extension="*", Flags=0)] |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
76 vd = VirtualDirParameters(Name="/", |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
77 Description = "ISAPI-WSGI Echo Test", |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
78 ScriptMaps = sm, |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
79 ScriptMapUpdate = "replace") |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
80 params.VirtualDirs = [vd] |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
81 HandleCommandLine(params) |
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 This script has two parts: First, when run directly using Python, it will |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
84 install a script map ISAPI handler into the root application of the default |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
85 website, and secondly it will be called from the ISAPI handler when invoked |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
86 from the website. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
87 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
88 The ISAPI handler is registered to all file extensions, so it will automatically |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
89 be the one handling all requests to the website. When the website starts the |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
90 ISAPI handler, it will start a thread pool managed wrapper around the paster |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
91 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
|
92 site will be processed through this logic henceforth. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
93 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
94 Authentication with Kallithea using IIS authentication modules |
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 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
|
98 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
|
99 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
100 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
|
101 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
|
102 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
|
103 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
|
104 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
|
105 Finally, save the changes on this page. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
106 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
107 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
|
108 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
|
109 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
|
110 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
|
111 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
|
112 external account*. Finally, save the changes. |
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 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
|
115 Windows authentication. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
116 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
117 Troubleshooting |
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 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
120 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
|
121 in Kallithea (or Kallithea's WSGI/paster middleware). Consequently, two |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
122 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
|
123 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
|
124 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
|
125 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
126 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
|
127 type the following in a console window:: |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
128 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
129 python -m win32traceutil |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
130 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
131 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
|
132 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
|
133 traces, making it a lot easier to identify issues. |