Mercurial > kallithea
annotate docs/installation_iis.rst @ 4954:14f063657078
i18n: updated translation for Dutch (Belgium)
Currently translated at 0.8% (9 of 1077 strings)
author | Sam Jaques <sam.jaques@me.com> |
---|---|
date | Tue, 31 Mar 2015 16:25:49 +0000 |
parents | 2dad9708c89f |
children | 22a3fa3c4254 |
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 |
4554
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
47 The ISAPI handler can be generated using:: |
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 paster install-iis my.ini --root=/ |
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 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
|
52 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
|
53 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
|
54 that ISAPI-WSGI is made:: |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
55 |
4554
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
56 python dispatch.py install |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
57 |
4554
2dad9708c89f
paster: add install-iis command to automate IIS handler generation
Henrik Stuart <hg@hstuart.dk>
parents:
4500
diff
changeset
|
58 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
|
59 ``_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
|
60 ``--root`` specified above pointing to ``_dispatch.dll``. |
4500
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
61 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
62 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
|
63 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
|
64 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
|
65 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
|
66 site will be processed through this logic henceforth. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
67 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
68 Authentication with Kallithea using IIS authentication modules |
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 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
71 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
|
72 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
|
73 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
74 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
|
75 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
|
76 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
|
77 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
|
78 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
|
79 Finally, save the changes on this page. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
80 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
81 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
|
82 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
|
83 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
|
84 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
|
85 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
|
86 external account*. Finally, save the changes. |
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 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
|
89 Windows authentication. |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
90 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
91 Troubleshooting |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
92 --------------- |
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 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
|
95 in Kallithea (or Kallithea's WSGI/paster middleware). Consequently, two |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
96 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
|
97 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
|
98 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
|
99 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
100 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
|
101 type the following in a console window:: |
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 python -m win32traceutil |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
104 |
e69d34136be5
docs: describe installation under IIS
Henrik Stuart <hg@hstuart.dk>
parents:
diff
changeset
|
105 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
|
106 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
|
107 traces, making it a lot easier to identify issues. |