Catalys...FastCGI(3)

okay so bestie, this is the Catalys...FastCGI(3) page from User Contributed Perl Documentation — yes, the title is literally truncated like that, no cap 🫶. It's the deployment guide for Catalyst::Manual::Deployment::nginx::FastCGI, all about putting Catalyst behind nginx, and we're gonna go through every single detail.

🌸 NAME 🌸

Catalyst::Manual::Deployment::nginx::FastCGI — deploying Catalyst with nginx. That's the whole vibe: Catalyst + nginx + FastCGI, bestie 💅.

🦋 nginx 🦋

Catalyst can run under nginx via FastCGI in a very similar way to the lighttpd standalone server — cute, same energy ✨.

nginx does not have its own internal FastCGI process manager, so you have to run the FastCGI service separately. Like, it's not built in; you're bringing the FastCGI party yourself 💅.

✨ Configuration ✨

To configure nginx, you need to set up the FastCGI parameters and the socket that your FastCGI daemon is listening on. That socket can be either a TCP socket or a Unix file socket. Both valid, both slay 🫶.

The server configuration block should look roughly like this:

server {
    listen $port;

    location / {
        fastcgi_param  QUERY_STRING       $query_string;
        fastcgi_param  REQUEST_METHOD     $request_method;
        fastcgi_param  CONTENT_TYPE       $content_type;
        fastcgi_param  CONTENT_LENGTH     $content_length;

        fastcgi_param  SCRIPT_NAME        '';
        fastcgi_param  PATH_INFO          $fastcgi_script_name;
        fastcgi_param  REQUEST_URI        $request_uri;
        fastcgi_param  DOCUMENT_URI       $document_uri;
        fastcgi_param  DOCUMENT_ROOT      $document_root;
        fastcgi_param  SERVER_PROTOCOL    $server_protocol;

        fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
        fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;

        fastcgi_param  REMOTE_ADDR        $remote_addr;
        fastcgi_param  REMOTE_PORT        $remote_port;
        fastcgi_param  SERVER_ADDR        $server_addr;
        fastcgi_param  SERVER_PORT        $server_port;
        fastcgi_param  SERVER_NAME        $server_name;

        # Adjust the socket for your applications!
        fastcgi_pass   unix:$docroot/myapp.socket;
    }
}

nginx's standard convention is to put the fastcgi_params in a separate file (usually something like /etc/nginx/fastcgi_params) and just include that file. Very modular, very clean ✨.

If you include the /etc/nginx/fastcgi_params that ships with your distribution — e.g. Debian — you need to adjust a couple of parameters for PSGI compatibility. Use something like this:

        include /etc/nginx/fastcgi_params;
        fastcgi_param SCRIPT_NAME '';
        fastcgi_param PATH_INFO   $fastcgi_script_name;

🎀 Non-root configuration 🎀

If you properly specify the PATH_INFO and SCRIPT_NAME parameters, your app will be accessible at any path. The SCRIPT_NAME variable is the prefix of your application, and PATH_INFO is everything in addition to that. Cute little split, right? 💖

As an example, if your app is rooted at /myapp, you'd configure:

    rewrite ^/myapp$ /myapp/ permanent;
    location /myapp/ {
        include /etc/nginx/fastcgi_params;
        fastcgi_param SCRIPT_NAME /myapp/;
        fastcgi_param PATH_INFO   $fastcgi_script_name;
        fastcgi_pass unix:/tmp/myapp.socket;
    }

$fastcgi_script_name would be /myapp/path/of/the/action. Catalyst will process this accordingly and set up the application base as expected. Iconic behavior, honestly 👑.

This behavior is somewhat different from Apache and lighttpd, but it's still functional.

heads up bestie: the rewrite may not be needed with newer versions of nginx, and the paths must be exactly as specified — the trailing slash in the location block and the SCRIPT_NAME are important. Do not skip the slash, I'm begging 🙈.

🔒 SSL 🔒

Make sure nginx passes this to your FastCGI. To make sure that happens, you need the following in your nginx config for the SSL vhost:

fastcgi_param  HTTPS on

🌈 MORE INFO 🌈

For more information on nginx, visit: https://www.nginx.com/ — go read the docs, bestie, they're right there 🦋.

👑 AUTHORS 👑

Catalyst Contributors, see Catalyst.pm. Legends, all of them 💜.

💖 COPYRIGHT 💖

This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. Slay, open source 🎀.

mwah 💋 — this page is from perl v5.42.0, dated 2024-03-23, and titled Catalys...FastCGI(3). Bye bestie, go deploy something iconic 🫶✨