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/www/example/.htpasswd;
root /home/user/www/;
}
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;
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.
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.