Nginx Configuration Files

On MageStack, Nginx has 4 separate configuration files per vhost defined under 2 different directories/scopes, ___general and ___rewrites.

Scope

Each configuration file serves its own purpose - knowing which to use first is answered by the scope you need to edit.

On MageStack, Nginx has two scopes, server and location

As MageStack defines location / {} as part of the main configuration, it means that you can no longer set this - so MageStack allows extension of this location by including another configuration file from that location.

To give you perspective and understanding, the main Nginx configuration looks like this,

Find the latest $static_file_extensions here.

http {

  map $request_uri $example_com_redirect {
    include /microcloud/domains/example/domains/example.com/___rewrites/example.com.redirect.map;
  }

  server {

    include ___general/example.com.conf;

    location ~* \.($static_file_extensions)$ {
      include ___general/example.com.location.static.conf;
      location ~* \.(js|css)$ {
        include ___general/example.com.location.semi-static.conf;
      }
    }

    location / {
      include ___rewrites/example.com.conf;
       ...
    }

    if ($example_com_redirect) {
      return 301 $example_com_redirect;
      break;
    }

}

This means that if you need to edit a setting inside of the location / scope, you should put that edit inside of ___rewrites/example.com.conf

If you want to edit properties for "static" files (ie. those defined above), they should go in ___general/example.com.location.static.conf

If you want to edit properties for "semi-static" files (eg. those that might be generated dynamically by Magento), our default definition is .css and .js files, they should go in ___general/example.com.location.semi-static.conf

And if you want to define an entirely new location, or apply a global setting to all locations, you should put it in ___general/example.com.conf

Configuration files

/microcloud/domains/.nginx-global-general.pre.conf

Defined at the start of the server {} scope for all vhosts on the entire stack. You put rules in this that you want to apply globally to all vhosts on the stack.

/microcloud/domains/.nginx-global-general.post.conf

Defined at the end of the server {} scope for all vhosts on the entire stack. You put rules in this that you want to apply globally to all vhosts on the stack.

___general/example.com.conf

Defined in the server {} scope.

This is the main global configuration and will generally take precedence over other locations. Variables or headers defined in other scopes will override this value.

Eg. This makes it possible to set set $magestack_debug true; in this scope, but disable it in another.

___general/example.com.location.static.conf

Defined in the server {} scope.

This configuration file is specifically provided for static content. The default MageStack definition for static content is jpeg|jpg|png|gif|ico|swf|gz|rar|txt|bzip|pdf|ttf|woff|htc

___general/example.com.location.semi-static.conf

Defined in the server {} scope.

This configuration file is specifically provided for static content. The default MageStack definition for static content is js|css

___rewrites/example.com.redirect.map

This is a powerful file used solely for the purpose of creating 301 redirects. If you have a large number of rewrite rules and do not need regular expression support, this is an incredibly efficient mechanism for mass redirect management.

The format of the file is as follows

Eg. /from /to;

___rewrites/example.com.conf

Defined in the location / {} scope.

You can still nest locations within this scope, but its purpose is usually best suited to listing simple rewrite rules.

Eg. rewrite /old/path /new/path permanent;

Applying changes

Unlike Apache's .htaccess file, which reflects changes in real-time (without requiring a service restart), Nginx behaves slightly differently. After each change to the configuration file, Nginx must be reloaded to reflect the changes.

For further instructions, learn more about changing and testing Nginx configuration.