lib/Catalyst/Manual/Deployment/IIS/FastCGI.pod

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