Commit | Line | Data |
45b58a85 |
1 | =head1 NAME |
2 | |
3 | Catalyst::Manual::Deployment::IIS::FastCGI - Deploying Catalyst with Microsoft IIS |
4 | |
0191b435 |
5 | =head1 Microsoft IIS |
45b58a85 |
6 | |
c07b1941 |
7 | Probably the best way to deploy a Catalyst application on IIS is by using |
8 | IIS as a front end proxy. However if you positively must use FastCGI (say |
9 | due to internal IT policies) then this manual shows you how. |
10 | |
5abded07 |
11 | It is possible to run Catalyst under IIS with FastCGI, but only on IIS |
12 | 6.0 (Microsoft Windows 2003), IIS 7.0 (Microsoft Windows 2008 and |
13 | Vista), and (hopefully) its successors. |
45b58a85 |
14 | |
5abded07 |
15 | FastCGI is sometimes said to be supported on IIS 5.1 (Windows XP), but |
16 | some features (specifically, wildcard mappings) are not supported. This |
17 | prevents Catalyst applications from running on the server. |
45b58a85 |
18 | |
19 | Let us assume that our server has the following layout: |
20 | |
21 | d:\WWW\WebApp\ path to our Catalyst application |
22 | d:\strawberry\perl\bin\perl.exe path to perl interpreter (with Catalyst installed) |
23 | c:\windows Windows directory |
24 | |
0191b435 |
25 | =head2 Setup IIS 6.0 (Windows 2003) |
45b58a85 |
26 | |
0191b435 |
27 | =over |
45b58a85 |
28 | |
29 | =item Install FastCGI extension for IIS 6.0 |
30 | |
5abded07 |
31 | FastCGI is not a standard part of IIS 6 - you have to install it |
32 | separately. For more info and the download, go to |
56a12748 |
33 | Lhttps://www.iis.net/downloads/microsoft/fastcgi-for-iis>. Choose the appropriate version |
5abded07 |
34 | (32-bit/64-bit); installation is quite simple (in fact no questions, no |
35 | options). |
45b58a85 |
36 | |
37 | =item Create a new website |
38 | |
39 | Open "Control Panel" > "Administrative Tools" > "Internet Information Services Manager". |
40 | Click "Action" > "New" > "Web Site". After you finish the installation wizard |
41 | you need to go to the new website's properties. |
42 | |
43 | =item Set website properties |
44 | |
5abded07 |
45 | On the tab "Web site", set proper values for: Site Description, IP |
46 | Address, TCP Port, SSL Port, etc. |
45b58a85 |
47 | |
5abded07 |
48 | On the tab "Home Directory" set the following: |
45b58a85 |
49 | |
50 | Local path: "d:\WWW\WebApp\root" |
51 | Local path permission flags: check only "Read" + "Log visits" |
52 | Execute permitions: "Scripts only" |
53 | |
54 | Click "Configuration" button (still on Home Directory tab) then click "Insert" |
5abded07 |
55 | the wildcard application mapping, and in the next dialog set: |
45b58a85 |
56 | |
57 | Executable: "c:\windows\system32\inetsrv\fcgiext.dll" |
58 | Uncheck: "Verify that file exists" |
59 | |
60 | Close all dialogs with "OK". |
61 | |
62 | =item Edit fcgiext.ini |
63 | |
64 | Put the following lines into c:\windows\system32\inetsrv\fcgiext.ini (on 64-bit |
65 | system c:\windows\syswow64\inetsrv\fcgiext.ini): |
66 | |
67 | [Types] |
68 | *:8=CatalystApp |
69 | ;replace 8 with the identification number of the newly created website |
70 | ;it is not so easy to get this number: |
71 | ; - you can use utility "c:\inetpub\adminscripts\adsutil.vbs" |
72 | ; to list websites: "cscript adsutil.vbs ENUM /P /W3SVC" |
73 | ; to get site name: "cscript adsutil.vbs GET /W3SVC/<number>/ServerComment" |
74 | ; to get all details: "cscript adsutil.vbs GET /W3SVC/<number>" |
75 | ; - or look where are the logs located: |
76 | ; c:\WINDOWS\SYSTEM32\Logfiles\W3SVC7\whatever.log |
77 | ; means that the corresponding number is "7" |
78 | ;if you are running just one website using FastCGI you can use '*=CatalystApp' |
79 | |
80 | [CatalystApp] |
81 | ExePath=d:\strawberry\perl\bin\perl.exe |
82 | Arguments="d:\WWW\WebApp\script\webapp_fastcgi.pl -e" |
83 | |
84 | ;by setting this you can instruct IIS to serve Catalyst static files |
85 | ;directly not via FastCGI (in case of any problems try 1) |
86 | IgnoreExistingFiles=0 |
87 | |
88 | ;do not be fooled by Microsoft doc talking about "IgnoreExistingDirectories" |
89 | ;that does not work and use "IgnoreDirectories" instead |
90 | IgnoreDirectories=1 |
91 | |
92 | =back |
93 | |
0191b435 |
94 | =head2 Setup IIS 7.0 (Windows 2008 and Vista) |
45b58a85 |
95 | |
506ff3c8 |
96 | Microsoft IIS 7.0 has built-in support for FastCGI so you do not have to |
97 | install any addons. |
45b58a85 |
98 | |
0191b435 |
99 | =over |
45b58a85 |
100 | |
101 | =item Necessary steps during IIS7 installation |
102 | |
5abded07 |
103 | During IIS7 installation, after you have added role "Web Server (IIS)" |
104 | you need to check to install the role feature "CGI" (do not be nervous |
105 | that it is not FastCGI). If you already have IIS7 installed you can add |
106 | the "CGI" role feature through "Control panel" > "Programs and |
107 | Features". |
45b58a85 |
108 | |
109 | =item Create a new website |
110 | |
506ff3c8 |
111 | Open "Control Panel" > "Administrative Tools" > "Internet Information Services |
112 | Manager" > "Add Web Site". |
45b58a85 |
113 | |
114 | site name: "CatalystSite" |
115 | content directory: "d:\WWW\WebApp\root" |
116 | binding: set proper IP address, port etc. |
117 | |
118 | =item Configure FastCGI |
119 | |
120 | You can configure FastCGI extension using commandline utility |
121 | "c:\windows\system32\inetsrv\appcmd.exe" |
122 | |
0191b435 |
123 | =over |
45b58a85 |
124 | |
125 | =item Configuring section "fastCgi" (it is a global setting) |
126 | |
127 | appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='d:\strawberry\perl\bin\perl.exe',arguments='d:\www\WebApp\script\webapp_fastcgi.pl -e',maxInstances='4',idleTimeout='300',activityTimeout='30',requestTimeout='90',instanceMaxRequests='1000',protocol='NamedPipe',flushNamedPipe='False']" /commit:apphost |
128 | |
129 | =item Configuring proper handler (it is a site related setting) |
130 | |
131 | appcmd.exe set config "CatalystSite" -section:system.webServer/handlers /+"[name='CatalystFastCGI',path='*',verb='GET,HEAD,POST',modules='FastCgiModule',scriptProcessor='d:\strawberry\perl\bin\perl.exe|d:\www\WebApp\script\webapp_fastcgi.pl -e',resourceType='Unspecified',requireAccess='Script']" /commit:apphost |
132 | |
5abded07 |
133 | Note: before launching the commands above, do not forget to change the |
134 | site name and paths to values relevant for your server setup. |
45b58a85 |
135 | |
136 | =back |
137 | |
138 | =back |
139 | |
689b0b14 |
140 | =head3 Setup of your application |
141 | |
142 | Note that you B<MUST> have the config setting C<use_request_uri_for_path> set to true |
143 | to work in IIS7 - if you do not have this then all sub paths in your application |
144 | (e.g. /foo/bar) will resolve to the root path, i.e. / |
145 | |
45b58a85 |
146 | =head1 AUTHORS |
147 | |
148 | Catalyst Contributors, see Catalyst.pm |
149 | |
150 | =head1 COPYRIGHT |
151 | |
152 | This library is free software. You can redistribute it and/or modify it under |
153 | the same terms as Perl itself. |
154 | |
155 | =cut |