Mercurial > kallithea

annotate docs/installation_iis.rst @ 4500:e69d34136be5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: describe installation under IIS
author Henrik Stuart <hg@hstuart.dk>
date Sun, 31 Aug 2014 12:11:50 +0200
parents
children 2dad9708c89f
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
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.