Translation(s): English

Nginx Web Server / Directory Structure


Nginx


/etc/nginx/

Nginx keeps it's configuration in the expected /etc/nginx directory. This directory is broken up as follows:

Path

Purpose

Ref.

./conf.d/*.conf

Extra configuration files.

#conf.d, #appincludes

./fastcgi.conf

Commonly configured directives (upstream version)

#params

./fastcgi_params

Commonly configured directives (nginx packaging team)

#params

./koi-utf

Nginx Character Set

#charset

./koi-win

Nginx Character Set

#charset

./mime.types

Maps file name extensions to MIME types of responses

#mimetypes

./nginx.conf

The primary configuration file.

#nginx.conf

./proxy_params

Commonly configured directives

#params

./scgi_params

Commonly configured directives

#params

./sites-available/*

Extra virtual host configuration files

-

./sites-enabled/*

Symlink to sites-available/<file> to enable vhost

-

./snippets/*.conf

Configuration snippets that can be included in configs

-

./default-server.d/*.conf

Files included in /etc/nginx/sites-available/default

#appincludes

./uwsgi_params

Commonly configured directives

#params

./win-utf

Nginx Character Set

#charset


/etc/nginx/nginx.conf

The first file that nginx reads when it starts is /etc/nginx/nginx.conf. This file is maintained by Nginx package maintainers and it is recommended that administrators avoid editing this file unless they also follow changes made by upstream.

It's advised to instead add customizations underneath of the conf.d/ directory which is described below.


/etc/nginx/conf.d/*.conf

The default nginx.conf file includes a line that will load additional configurations files into the http { } context. In most cases, options previously specified in the primary nginx.conf file can be overridden by creating a file at this location.

Example: /etc/nginx/conf.d/ssl-tweaks.conf

add_header Strict-Transport-Security "max-age=31536000; includeSubdomains";
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
ssl_ciphers 'kEECDH+CHACHA kEECDH+AESGCM HIGH+kEECDH AESGCM 3DES !SRP !PSK !DSS !MD5 !LOW !MEDIUM !aNULL !eNULL !DH !kECDH';


Extra Parameters

Some location blocks typically have extra configuration that is preferred to not be specified in a higher context. This is most often seen when running dynamic web applications such as Wordpress, Drupal, or Django. Depending on the protocol the backend application server speaks, a different set of parameters will need to be included.

proxy_params:

This file is most commonly included when Nginx is acting as a reverse proxy.

include /etc/nginx/proxy_params;
proxy_pass http://localhost:8000;

fastcgi_params:

This is used to speak to applications servers that speak the FastCGI protocol. Most commonly, this will be associated with php-fpm.

include fastcgi_params;
fastcgi_split_path_info ^(.+?\.php)(|/.*)$;
fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;

scgi_params:

This file is used when passing requests to an SCGI server.

include scgi_params;
scgi_pass unix:/var/run/rpc.sock;

uwsgi_params:

In most cases, this file is used when proxying requests to the uwsgi application.

include uwsgi_params;
uwsgi_pass unix:/run/uwsgi/sockets/drupal7.sock;


Packaged Applications

It's often expected that commands like apt-get install drupal8 will result in a fully configured and running Drupal installation. Because Debian is magic, there's no reason choosing Nginx should keep this from being a reality.

These directories exist for applications such as Drupal, Wordpress, or any other packaged web application to create configurations that are included when nginx is reloaded. These files will be included in the default server block.

Applications are expected to create files with the following syntax:

Files underneath of the conf.d/ [1] directory should restrict their use to activities such as creating variables using the map directive. Additionally, any variables created should be prefixed with their respective package name.

Example: /etc/nginx/conf.d/pkg_drupal8.conf

map $http_cookie $drupal8_php_sess {
    default 0;
    ~SESS 1; # PHP session cookie
}

Files underneath of the default-server.d [2] are included in the default server block. It is expected that everything in this file be wrapped in a location directive respective to the package name.

Example: /etc/nginx/default-server.d/pkg_drupal8.conf

location ^~ /drupal8 {
    root /usr/share/drupal8;

    location ~ ^/drupal8/sites/.*/private/ {
        return 403;
    }

    location /drupal8/ {
        try_files $uri /index.php?$query_string;
    }

    location ~ '\.php$|^/update.php' {
        fastcgi_split_path_info ^(.+?\.php)(|/.*)$;
        include fastcgi_params;
        fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;
    }
}

Package maintainers are strongly encouraged to contact the Nginx packaging team in order to build quality configuration files that meet these standards.

init

If your package sets configuration files, as described here, it's likely you'll want to restart the nginx service for the changes to take effect. To help ensure we keep servers running, postinst scripts should use the reload feature of nginx and not restart. Additionally, nginx -t can be called to test that the current nginx configuration is valid before even attempting to reload the service.

uwsgi

The nginx packaging team recommends the use of uwsgi to run applications. This provides a consistent pattern to administrators and users. It also allows the nginx packaging team to more efficiently and more effectively help with web application packaging.

We recommend the use of: /etc/uwsgi/apps-available/pkg_<package_name>.ini

Symlink to there from: /etc/uwsgi/apps-enabled/pkg_<package_name>.ini

Example: /etc/uwsgi/apps-available/pkg_drupal7.ini

[uwsgi]
socket = /run/uwsgi/sockets/drupal7.sock
chdir = /usr/share/drupal7
master = true
plugins = php
file = index.php
uid = www-data
gid = www-data

Please note... this is a new structure and we are working to build more complete documentation to provide examples for all situations you may want to offer.