Nginx: Difference between revisions

Latest revision as of 11:29, 16 December 2025

This page requires updating. Please do so and remove this template when finished.

Nginx [engine x] is an HTTP and reverse proxy server, as well as a mail proxy server, written by Igor Sysoev. The nginx project started with a strong focus on high concurrency, high performance and low memory usage. It is licensed under the 2-clause BSD-like license and it runs on Linux, BSD variants, Mac OS X, Solaris, AIX, HP-UX, as well as on other *nix flavours. It also has a proof of concept port for Microsoft Windows.

The following is community-contributed documentation on Nginx configuration. Amendments and additions are welcome.

Nginx configuration

PHP-FPM

Nginx is usually configured to interface with PHP via php-fpm. This is both fast and robust.

PHP-FPM's default behaviour for pools is usually to restrict the execution of scripts to a specific extension, i.e. .php. You should ensure that this behaviour is configured within your particular package/distribution, e.g. for debian,

/etc/php/8.2/fpm/pool.d/www.conf

security.limit_extensions = .php

Nginx

Since version 4.5, Moodle makes use of both 'slash arguments', and a Routing Engine.

Both of these require that you correctly configure your server to correctly split on the filename. The use of the try_files directive is also known to interfere with the FastCGI configuration unless properly configured.

If not correctly configured, you will see issues such as missing images and CSS.

Note: Since Moodle 5.1, a /public directory has been added to the codebase. Nginx must be configured so that the document root points to this directory (e.g. root /srv/moodle/public;). This ensures only web-accessible files are served. See the restructure guide for more details.

FastCGI Configuration

The following configuration is known to work with Moodle 4.5 and above.

location ~ \.php(/|$) {
  # Split the path info based on URI.
  fastcgi_split_path_info ^(.+\.php)(/.*)$;

  # Note: Store the original path_info. It will be wiped out in a moment by try_files.
  set $path_info $fastcgi_path_info;

  # Look for the php file, trying a trailing slash for directories if required. 
  # Finally, send the request to the router - r.php - as a fallback.
  try_files $fastcgi_script_name $fastcgi_script_name/ /r.php$is_args$args;

  # File was found - pass to fastcgi.
  fastcgi_pass   127.0.0.1:9000;
  # Alternately, pass to unix socket (depends on pool listen configuration)
  # fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;

  include        fastcgi_params;

  # Re-apply the path_info after including fastcgi_params.
  fastcgi_param PATH_INFO $path_info;
  fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
  fastcgi_param DOCUMENT_ROOT $realpath_root;
}

Routing Engine

If your Moodle site is hosted from the root location, you can use the following configuration to route requests to the correct file.

location / {
    try_files $uri $uri/ /r.php$is_args$args;
}

Where your Moodle site is hosted in a sub-directory, you must specify the sub-directory in the location block.

location /moodle/ {
  try_files $uri $uri/ /moodle/r.php$is_args$args;
}

Hiding internal files

# Hide all dot files but allow "Well-Known URIs" as per RFC 5785 
location ~ /\.(?!well-known).* {
    return 404;
} 

# This should be after the php fpm rule and very close to the last nginx ruleset. 
# Don't allow direct access to various internal files. See MDL-69333 
location ~ (/vendor/|/node_modules/|composer\.json|/readme|/README|readme\.txt|/upgrade\.txt|/UPGRADING\.md|db/install\.xml|/fixtures/|/behat/|phpunit\.xml|\.lock|environment\.xml) { 
    deny all;
    return 404; 
}

XSendfile aka X-Accel-Redirect

Setting Moodle and Nginx to use XSendfile functionality is a big win as it frees PHP from delivering files allowing Nginx to do what it does best, i.e. deliver files.

Enable xsendfile for Nginx in Moodles config.php, this is documented in the config-dist.php, a minimal configuration look like this,

$CFG->xsendfile = 'X-Accel-Redirect';
$CFG->xsendfilealiases = array(
    '/dataroot/' => $CFG->dataroot
);

Accompany this with a matching 'location' block in your nginx server configuration.

location /dataroot/ {
    internal;
    alias <full_moodledata_path>; # ensure the path ends with /
}

The definition of 'internal' here is critical as it prevents client access to your dataroot.

Load Balancer Hints (AWS)

If you're using an AWS load balancer in front your infrastructure, you can set up some of the configuration above, preventing traffic to go forward. Here is the configuration applied to hide files, with a few considerations due to known limitations:

100 total rules per application load balancer
5 condition values per rule
5 wildcards per rule
5 weighted target groups per rule:

[
    {
        "Conditions": [
            {
                "Field": "path-pattern", 
                "Values": [
                    "*/.*", 
                    "*/upgrade.txt", 
                    "*/db/install.xml",
                    "*/README.md"
                ], 
                "PathPatternConfig": {
                    "Values": [
                        "*/.*", 
                        "*/upgrade.txt", 
                        "*/db/install.xml",
                        "*/README.md"
                    ]
                }
            }
        ], 
        "Actions": [
            {
                "Type": "fixed-response", 
                "Order": 1, 
                "FixedResponseConfig": {
                    "ContentType": "text/html", 
                    "MessageBody": "<html>\n<head><title>404 Not Found</title></head>\n<body>\n<center><h1>404 Not Found</h1></center>\n<hr>\n</body>\n</html>", 
                    "StatusCode": "404"
                }
            }
        ]
    }, 
    {
        "Conditions": [
            {
                "Field": "path-pattern", 
                "Values": [
                    "*/composer.json", 
                    "*/Gruntfile.js",
                    "*.lock", 
                    "*/environtment.xml",
                    "*/readme.txt"
                ], 
                "PathPatternConfig": {
                    "Values": [
                        "*/composer.json", 
                        "*/Gruntfile.js",
                        "*.lock", 
                        "*/environtment.xml",
                        "*/readme.txt"
                    ]
                }
            }
        ], 
        "Actions": [ #### Same as above
            ...
        ]
    }, 
    {
        "Conditions": [
            {
                "Field": "path-pattern", 
                "Values": [
                    "*/fixtures/*", 
                    "*/behat/*", 
                    "*/phpunit.xml"
                ], 
                "PathPatternConfig": {
                    "Values": [
                        "*/fixtures/*", 
                        "*/behat/*", 
                        "*/phpunit.xml"
                    ]
                }
            }
        ], 
        "Actions": [ #### Same as above
            ...
        ]
    }
]

Documentation