Nginx source control configuration

We understand that some people have custom requirements when it comes to Nginx.
To support this MDOQ allows you to use your own Nginx templates.

You do not need to do this, MDOQ will use default templates if non exist, which will work in most cases

MDOQ Directories

MDOQ uses the following directories within your repository, if they don't exist MDOQ will create them. If you don't want to customise MDOQ's behaviour just ignore them.

Templates Directory

Location: mdoq/nginx/templates
This is where MDOQ looks for Nginx configuration. MDOQ uses the Mustache template engine to process any templates found.
For a full list of the variables available in your templates see Temaplte Variables
There are 3 types of templates, identified by their suffix.

Site Configuration

Suffix: _site.conf
The configuration for your site. This can be declared per domain (e.g www.example.com_site.conf) or for all domains (e.g default_site.conf)
When creating an instance if no templates are found MDOQ will automatically add default_site.conf.
See Examples for some examples.

HTTP Configuration

Suffix: _http.conf
Nginx configuration to be evaluated upon receipt of a HTTP request before being passed to your site configuration. (This is where you might add redirects)
This again can be declared per domain (e.g www.example.com_http.conf) or for all domains (e,g default_http.conf)
See Examples for some examples.

HTTPS Configuration

Suffix: _https.conf
Nginx configuration to be evaluated upon receipt of a HTTPS request before being passed to your site configuration. (This is where you might add redirects, or proxy pass to a blog)
This again can be declared per domain (e.g www.example.com_https.conf) or for all domains (e,g default_https.conf)
See Examples for some examples.

N.B: When creating an instance the urls are MDOQ-ified however when looking for templates MDOQ will look for the production domains.
For example if your production site is at www.example.com, the MDOQ url might look something like www-example-com.50.mdoq.io, but MDOQ will still look for the templates: www.example.com_site.conf, www.example.com_https.conf and www.example.com_http.conf

Includes Directory

Location: mdoq/nginx/includes
Files in this location will be includable from within your other templates.
This could be used to specify a list of allowed IPs and include across multiple sites.
If you have the file: mdoq/nginx/includes/common_redirects.conf
You could include this in your _https.conf and _http.conf with

include {{includes_directory}}/common_redirects.conf

Generated Directory

Location: mdoq/nginx/generated
This is where MDOQ generates the entrypoint configuration to as well as the shared configuration
Files in this directory will be loaded by Nginx, making any variables/configuration declared available in all other files.
There are some reserved files that will be overwritten on creation of the component, as such they aren't recommended to be in source control, however other files can be included in source control.
Reserved File Names

• _.conf
• shared.conf
• your_site_domain.conf - MDOQ will generate a .conf file for all your domains (e.g www.example.com.conf).
  See Examples for some examples.

Making changes to files within the Nginx directory will not have any imediate effect. To see changes take effect you need to recreate the Nginx component.
It is recommended to try changes out on an instance before production.

Types of configuration

MDOQ splits Nginx config into 3 types:

• Entrypoint - responsible for listening on the correct ports and dealing will SSL termination
• Shared - responsible for providing variables that are accessible everywhere (Such as $MAGE_RUN_CODE)
• Includes - Nginx configuration files that are used to serve the site.

Entrypoint Configuration

The entrypoint configuration is responsible for listening on the correct ports and dealing with SSL termination.
An entrypoint is generated for each enabled site/domain within Magento.
You cannot provide your own template for this part, though you can configure certain parameters to change how Nginx is configured/the entrypoint behaves.

• Additional Custom Params are included in this file. Allowing you to add Nginx configuration as server block level
  You can see these in the entrypoint template below, anwhere it shows:

  {{#custom_variables}}
  {{key}} {{value}};
  {{/custom_variables}}

• Additional SSL Configuration are also included in this file. Allowing you to configure how SSL is configured.
  You can see these in the entrypoint template below, anywhere it shows:

  {{#ssl_configuration}}
  {{key}} {{value}};
  {{/ssl_configuration}}

Entrypoint Template

HTTP request
server {
    ...

    {{#custom_variables}}
    {{key}} {{value}};
    {{/custom_variables}}

    {{#http_include_path}}
    include {{ http_include_path }};
    {{/http_include_path}}

    {{#force_https}}
    return 301 https://$server_name$request_uri;
    {{/force_https}}

    {{^force_https}}
    include {{ site_include_path }};
    {{/force_https}}

    ...
}

## HTTPS request
server {
    ...

    {{#custom_variables}}
    {{key}} {{value}};
    {{/custom_variables}}

    {{#ssl_configuration}}
    {{key}} {{value}};
    {{/ssl_configuration}}

    {{#https_include_path}}
    include {{ https_include_path }};
    {{/https_include_path}}

    ...
}

Check out Examples for more information

Shared Configuration

Is responsible for providing variables that are accessible everywhere (Such as $MAGE_RUN_CODE).
The file isn't configurable, but you can see the contents at mdoq/nginx/generated/shared.conf

Includes Configuration

Nginx configuration files that are used to serve the site. This includes, your _site.conf, _http.conf and https.conf. This is because they are included by the entrypoint.

Template Variables