Translation(s): English

Nginx Web Server / Directory Structure



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





Extra configuration files.

#conf.d, #appincludes


Commonly configured directives (nginx packaging team)



Commonly configured directives (upstream version)



Nginx Character Set



Nginx Character Set



Maps file name extensions to MIME types of responses



The primary configuration file.



Commonly configured directives



Commonly configured directives



Extra virtual host configuration files



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



Configuration snippets that can be included in configs



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



Commonly configured directives



Nginx Character Set



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.


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;

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.


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

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


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;


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

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


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.

We have provided directories for applications such as Drupal or 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 apps.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/apps.d/pkg_drupal7.conf

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

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

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

    location ~ '\.php$|^/drupal7/update.php' {
        uwsgi_modifier1 14;
        include uwsgi_params;
        uwsgi_pass unix:/run/uwsgi/app/pkg_drupal7/socket;

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

upstream providers

In addition to conf.d/pkg_<name>.conf, some packages may want to provide an upstream proxy location. The easiest example is php-fpm or uwsgi-plugin-php which may want to offer an upstream block for their application server.

In these situations, a package may provide an upstream { } block. This provider should be as generic as possible and start with the _provider prefix.

Example: php-fpm: /etc/nginx/conf.d/pkg_php-fpm

upstream _provider_php {
    server unix:/var/run/php7-fpm.sock;

If uwsgi-plugin-php and php-fpm are both installed and provide a similar file, then two files will both provide the same upstream name and a reload or restart will fail. This is a situation for the user to handle.


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.


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

plugins = php
master = true
workers = 2
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.

Further reading: Nginx/uwsgi