nginx

You can add specific configurations to nginx on serveral levels.

Website Level

The file ~/cnf/nginx.conf will be included within the server {} configuration of the current vhost. It is used to alter the configuration of the current website.

Tip

After changes, reload nginx with the nginx-reload shortcut.

Tip

For Details, see the Server Block Examples and Rewrite Rule documentation

Examples

Add Basic Auth to Location

location ~* "^/example/" {
    auth_basic "Example name";
    auth_basic_user_file /home/user/cnf/.htpasswd;
    root /home/user/www/;

    # if desired, copy try_files from root
}

IP Protection

# allow your ip
allow <your-address>;

# allow our monitoring
allow 2a04:503:0:1008::112;
allow 185.17.70.112;
deny all;

Custom MIME Type

include mime.types;
types {
    text/cache-manifest appcache;
}

Favicon per Domain

location = /favicon.ico {
    try_files /favicons/$http_host.ico /favicons/default.ico
}

DCV (Domain Control Validation)

location ~ ^\/.well-known\/pki-validation\/fileauth\.txt$ {
        allow all;
        satisfy any;
        alias /path/to/fileauth.txt;
}

ACME Challenge

location ~ ^\/.well-known\/acme-challenge\/(.*)$ {
    allow all;
    satisfy any;
    alias /usr/local/dehydrated/.acme-challenges/$1;
}

Custom Maintenance Page

error_page 404 /error/404.html;
error_page 503 /error/maintenance.html;

Tip

You will need to define your own nginx location or disable our error page for this to work.

Context Specific

While the main configuration should go into ~/cnf/nginx.conf, you can also use Context specific files which are taken into account when the repsective context is used only:

~/cnf/nginx-prod.conf
~/cnf/nginx-stage.conf
~/cnf/nginx-dev.conf

These files will be loaded, but are not created by default.

Server Level

The file /etc/nginx/custom/http.conf is directly integrated in http { }, before server { } and can only be edited with the Generic Admin User user. You can use this file for settings that must be configured at nginx http context.

Custom Configuration Include

Include your own, external configuration files within server { } or http { } by including the following configuration to your server’s Custom JSON:

{
  "nginx::global_config::server_file": "/absolut/path/to/your/server.conf",
  "nginx::global_config::http_file": "/absolut/path/to/your/http.conf"
}

Tip

This is especially useful, when you deploy your own configuration with Git Repository Deployment.

Predefined Variables

The following variables are predefined and can be used within your NGINX configuration.

$username: Website Name
$context: Website Context

Custom Webroot

By default, the webroot directory is choosen according vendor recommendations, depending on the selected type. Some deployment workflows require other locations, which you can select through the custom_webroot string within the Custom JSON Website Level Configuration:

{
  "custom_webroot": "deploy/current/html"
}

Warning

The directory specified here needs to be a real directory. Symlinks are not allowed. This applies only to the last directory though (in the example above, current can be a symlink but html cannot).

Custom Log Format

To alter the format used for nginx access logs, for example due to privacy reasons, you can use the website::wrapper::nginx::log_format string within the Custom JSON Server Level Configuration.

This configuration is only available globally for all websites on a server, to change to default combined format to replace the actual visitors ip address with 127.0.0.1, use the following example:

{
  "website::wrapper::nginx::log_format": "127.0.0.1 - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\""
}

Listen

By default, nginx will bind to the primary IP address of the eth0 interface and the 80/443 port. You can specify listen options explicitly per website, for example to use in concunction with Varnish.

The following options are available within the Custom JSON Website Level Configuration:

{
  "listen_ip": "127.0.0.1",
  "listen_port": "8080",
  "listen_options": "option_value",
  "ipv6_listen_ip": "::1",
  "ipv6_listen_port": "8080",
  "ipv6_listen_options": "option_value"
}

Tip

If you set listen_options and ipv6_listen_options to default_server, the corresponding web page becomes the default server and listens to every server name. This is useful for landing/fallback pages where you do not want to add every host name individually.

Error Pages

We use branded error pages for Webserver status codes like 403 and so on. To disable them, set the following Custom JSON Website Level Configuration:

{
   "error_page": false
}