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.


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


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


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

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"


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.

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"


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, use the following example:

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


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": "",
  "listen_port": "8080",
  "listen_options": "option_value",
  "ipv6_listen_ip": "::1",
  "ipv6_listen_port": "8080",
  "ipv6_listen_options": "option_value"


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.