Commit | Line | Data |
45b58a85 |
1 | =head1 NAME |
2 | |
3 | Catalyst::Manual::Deployment::nginx::FastCGI - Deploying Catalyst with nginx |
4 | |
0191b435 |
5 | =head1 nginx |
45b58a85 |
6 | |
7 | Catalyst runs under nginx via FastCGI in a similar fashion as the lighttpd |
5abded07 |
8 | standalone server. |
45b58a85 |
9 | |
10 | nginx does not have its own internal FastCGI process manager, so you must run |
11 | the FastCGI service separately. |
12 | |
0191b435 |
13 | =head2 Configuration |
45b58a85 |
14 | |
15 | To configure nginx, you must configure the FastCGI parameters and also the |
16 | socket your FastCGI daemon is listening on. It can be either a TCP socket |
17 | or a Unix file socket. |
18 | |
19 | The server configuration block should look roughly like: |
20 | |
21 | server { |
22 | listen $port; |
23 | |
24 | location / { |
25 | fastcgi_param QUERY_STRING $query_string; |
26 | fastcgi_param REQUEST_METHOD $request_method; |
27 | fastcgi_param CONTENT_TYPE $content_type; |
28 | fastcgi_param CONTENT_LENGTH $content_length; |
29 | |
19d5a2d2 |
30 | fastcgi_param SCRIPT_NAME ''; |
45b58a85 |
31 | fastcgi_param PATH_INFO $fastcgi_script_name; |
32 | fastcgi_param REQUEST_URI $request_uri; |
33 | fastcgi_param DOCUMENT_URI $document_uri; |
34 | fastcgi_param DOCUMENT_ROOT $document_root; |
35 | fastcgi_param SERVER_PROTOCOL $server_protocol; |
36 | |
37 | fastcgi_param GATEWAY_INTERFACE CGI/1.1; |
38 | fastcgi_param SERVER_SOFTWARE nginx/$nginx_version; |
39 | |
40 | fastcgi_param REMOTE_ADDR $remote_addr; |
41 | fastcgi_param REMOTE_PORT $remote_port; |
42 | fastcgi_param SERVER_ADDR $server_addr; |
43 | fastcgi_param SERVER_PORT $server_port; |
44 | fastcgi_param SERVER_NAME $server_name; |
48bee5f2 |
45 | |
45b58a85 |
46 | # Adjust the socket for your applications! |
47 | fastcgi_pass unix:$docroot/myapp.socket; |
48 | } |
49 | } |
50 | |
51 | It is the standard convention of nginx to include the fastcgi_params in a |
52 | separate file (usually something like C</etc/nginx/fastcgi_params>) and |
53 | simply include that file. |
54 | |
19d5a2d2 |
55 | If you include the C</etc/nginx/fastcgi_params> that comes with your |
56 | distribution, e.g. Debian, you need to adjust a couple of parameters for PSGI |
57 | compatibility, use something like this: |
58 | |
59 | include /etc/nginx/fastcgi_params; |
60 | fastcgi_param SCRIPT_NAME ''; |
61 | fastcgi_param PATH_INFO $fastcgi_script_name; |
62 | |
0191b435 |
63 | =head2 Non-root configuration |
45b58a85 |
64 | |
65 | If you properly specify the PATH_INFO and SCRIPT_NAME parameters your |
66 | application will be accessible at any path. The SCRIPT_NAME variable is the |
67 | prefix of your application, and PATH_INFO would be everything in addition. |
68 | |
69 | As an example, if your application is rooted at /myapp, you would configure: |
70 | |
d38b4654 |
71 | rewrite ^/myapp$ /myapp/ permanent; |
72 | location /myapp/ { |
73 | include /etc/nginx/fastcgi_params; |
74 | fastcgi_param SCRIPT_NAME /myapp/; |
75 | fastcgi_param PATH_INFO $fastcgi_script_name; |
09300532 |
76 | fastcgi_pass unix:/tmp/myapp.socket; |
d38b4654 |
77 | } |
45b58a85 |
78 | |
79 | C<$fastcgi_script_name> would be "/myapp/path/of/the/action". Catalyst will |
80 | process this accordingly and setup the application base as expected. |
81 | |
5abded07 |
82 | This behavior is somewhat different from Apache and lighttpd, but is still |
45b58a85 |
83 | functional. |
84 | |
d38b4654 |
85 | Note that the rewrite may not be needed with newer versions of nginx, |
86 | and the paths must be exactly as specified - the trailing slash in the |
09300532 |
87 | location block and the SCRIPT_NAME are important. |
d38b4654 |
88 | |
48bee5f2 |
89 | =head2 SSL |
90 | |
91 | Make sure that nginx passes this to your fastcgi. To ensure this, you need |
92 | the following in your nginx config for the SSL vhost: |
93 | |
94 | fastcgi_param HTTPS on |
95 | |
96 | =head1 MORE INFO |
97 | |
45b58a85 |
98 | For more information on nginx, visit: |
99 | L<http://nginx.net> |
100 | |
101 | =head1 AUTHORS |
102 | |
103 | Catalyst Contributors, see Catalyst.pm |
104 | |
105 | =head1 COPYRIGHT |
106 | |
107 | This library is free software. You can redistribute it and/or modify it under |
108 | the same terms as Perl itself. |
109 | |
110 | =cut |