Differences between revisions 9 and 10
Revision 9 as of 2016-10-30 08:22:28
Size: 7191
Editor: ?MichaelLustfield
Comment:
Revision 10 as of 2016-11-10 06:43:38
Size: 7948
Editor: ?MichaelLustfield
Comment:
Deletions are marked like this. Additions are marked like this.
Line 110: Line 110:
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. 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.
Line 115: Line 115:
 * [2] /etc/nginx/apps.d/default_include_<package_name>.conf  * [2] /etc/nginx/apps.d/pkg_<package_name>.conf
Line 152: Line 152:
== 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.

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 (nginx packaging team)

#params

./fastcgi_params

Commonly configured directives (upstream version)

#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

-

./apps.d/*.conf

Files included by /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.

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:

  • [1] /etc/nginx/conf.d/pkg_<package_name>.conf

  • [2] /etc/nginx/apps.d/pkg_<package_name>.conf

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.

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]
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