NGINX Docker Setup
- NGINX Configuration Overview
- Testing Configuration
- Location Context Modifier
- Try Files Directive
- Structuring the Main Configuration File
- Setting up the Server Context
- Docker Compose
I want to create a template configuration for the Alpine-based NGINX Docker image from DockerHub: nginx:stable-alpine. The idea is to have folder with configuration files that I can modify - according to my project - and then mount as a volume into vanilla NGINX container to proxy my web applications:
docker run -d -p 80:80 -v /opt/nginx_config:/etc/nginx/conf.d --name nginx nginx:stable-alpine
NGINX Configuration Overview
The default NGINX configuration file is structured like this:
# main
...
events {
...
}
http {
server {
location {
...
}
}
}
Each Block in the configuration file:
main {{events {http { server { location {}}}}}}
Is called a Context. Each Context holds Directives which are parameter / value pairs like server_name localhost;. Such blocks can be separated from the main configuration file and then included using the include keyword:
include /etc/nginx/conf.d/*.conf;
Testing Configuration
After make changes to your configuration file you can validate it in NGINX without having to reload your service:
nginx -t
To apply those changes you have to reload or restart the NGINX service. The restart will stop the service and start it again, while the reload will keep the original process running. In the latter case, if something goes wrong with the configuration update, it will simply be discarded and your server stays online with the old configuration:
systemctl reload nginx
systemctl restart nginx
However, since the Docker image does not use SystemD to run the service, you can test the configuration inside the NGINX docker container but then have to restart the container to have it take effect.
docker exec -ti name-or-id-of-my-nginx-container nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
docker stop name-or-id-of-my-nginx-container
docker start name-or-id-of-my-nginx-container
Location Context Modifier
The location match defines what NGINX checks the incoming request against. How the match is applied can be influenced by a modifier:
| Modifier | Description |
|---|---|
| none | matched as prefix value |
= | matched as an exact value |
~ | matched as case sensitive regular expression |
~* | matched as case insensitive regular expression |
^~ | matched as prefix value with higher importance than a regular expression |
The modifiers are processed in the following order:
| Order | Modifier |
|---|---|
| 1 | = |
| 2 | ^~ |
| 3 | ~ and ~* |
| 4 | none |
Prefix
location /de {
}
No modifier matches as a prefix example matches are:
http://URL/de
http://URL/de123
http://URL/deutsch
etc.
Exact Value
location = /de {
}
Only an exact match will pass:
http://URL/de
Case Sensitive Regular Expression
location ~ /de[0-9] {
}
location ~ /de[a-z] {
}
This regular expression expects that the /de is either followed by numbers or by non-capital letters. Capital letters or mixed numbers and small letters will not match:
http://URL/de122
http://URL/deutsch
etc.
Case Insensitive Regular Expression
location ~ /de[0-9] {
}
location ~ /de[a-z] {
}
This regular expression expects that the /de is either followed by numbers or by letters. Mixed numbers and small letters will not match:
http://URL/de122
http://URL/deutsch
http://URL/deUTSCH
etc.
Try Files Directive
The try_files directive to match the incoming URL to different setups - for example to $uri or $uri/ with a trailing backslash or to a static file:
location / {
try_files $uri $uri/ /index.html;
}
NGINX will first try to find an exact match. Then try to add a trailing backslash. And lastly redirect you to the front page if no other fit was found.
Structuring the Main Configuration File
/etc/nginx/nginx.conf
user nginx;
worker_processes auto;
worker_rlimit_nofile 15000;
pid /var/run/nginx.pid;
include /usr/share/nginx/modules/*.conf;
events {
worker_connections 2048;
multi_accept on;
use epoll;
}
http {
default_type application/octet-stream;
# access_log /var/log/nginx/access.log;
# activate the server access log only when needed
access_log off;
error_log /var/log/nginx/error.log;
# don't display server version on error pages
server_tokens off;
server_names_hash_bucket_size 64;
include /etc/nginx/mime.types;
sendfile on;
tcp_nopush on;
tcp_nodelay on;
charset utf-8;
source_charset utf-8;
charset_types text/xml text/plain text/vnd.wap.wml application/javascript application/rss+xml;
include /etc/nginx/conf.d/default.conf;
include /etc/nginx/conf.d/buffers.conf;
include /etc/nginx/conf.d/timeouts.conf;
# Only activate caching in production
# include /etc/nginx/conf.d/cache.conf;
include /etc/nginx/conf.d/gzip.conf;
}
Set SELinux policy to allow setrlimit (
worker_rlimit_nofile):setsebool -P https_setrlimit 1. A low r limit might lead to an error message of too many open files under load.
This configuration file is missing the server and location context. Both of them will reside in a separate file in the included conf.d directory called default.conf. Along side we also include a couple of configuration files:
/etc/nginx/conf.d/buffers.conf
client_body_buffer_size 10k;
client_header_buffer_size 1k;
client_max_body_size 8m;
large_client_header_buffers 2 1k;
# large_client_header_buffers directive needs to be increased
# large_client_header_buffers 4 32k;
/etc/nginx/conf.d/timeouts.conf
client_header_timeout 3m;
client_body_timeout 3m;
keepalive_timeout 100;
keepalive_requests 1000;
send_timeout 3m;
/etc/nginx/conf.d/cache.conf
open_file_cache max=1500 inactive=20s;
open_file_cache_valid 30s;
open_file_cache_min_uses 5;
open_file_cache_errors off;
/etc/nginx/conf.d/gzip.conf
gzip on;
gzip_disable "MSIE [1-6]\.(?!.*SV1)";;
gzip_vary on;
gzip_proxied no-cache no-store private expired;
gzip_comp_level 5;
gzip_min_length 256;
gzip_buffers 16 8k;
gzip_http_version 1.1;
gzip_types text/plain text/css application/json application/javascript
text/xml application/xml application/xml+rss text/javascript
image/svg+xml application/xhtml+xml application/atom+xml application/x-javascript;
Setting up the Server Context
The application that I am serving has a path prefix to /en/. That means I have to redirect all incoming traffic on / to /en/. The static HTML content that I am serving lies in /opt/test-static/public and has to be set as the root directory for my server.
/etc/nginx/conf.d/default.conf
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name localhost;
root /opt/test-static/public;
index index.html;
location = / {
rewrite ^/(.*)$ /en/$1 permanent;
}
location /en/ {
try_files $uri $uri/ $uri.html =404;
include /etc/nginx/conf.d/header.conf;
}
location ~ /en/download_area/.* {
root /opt/downloads;
# deactivate autoindex to use try_files
# try_files $uri /en/download_area/morning.gif;
autoindex on;
autoindex_exact_size off;
autoindex_format html;
autoindex_localtime on;
}
error_page 404 /en/404.html;
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/share/nginx/html;
}
}
/etc/nginx/conf.d/header.conf
add_header Cache-Control "public, must-revalidate, proxy-revalidate, max-age=0";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-NginX-Proxy true;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto http;
proxy_hide_header X-Frame-Options;
proxy_set_header Accept-Encoding "";
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
proxy_max_temp_file_size 0;
proxy_redirect off;
proxy_read_timeout 240s;
Docker Compose
version: '3.8'
services:
ingress:
image: nginx:stable-alpine
container_name: ingress
networks:
- gateway
ports:
- '80:80'
- '443:443'
restart: unless-stopped
volumes:
- /opt/docker-ingress/configuration/conf.d:/etc/nginx/conf.d
- /opt/docker-ingress/configuration/nginx.conf:/etc/nginx/nginx.conf
- /opt/test-static/public:/opt/test-static/public
- /opt/downloads:/opt/downloads
networks:
gateway: {}
Tree structure for the mounted download directory:
/opt/downloads
└── en
└── download_area
├── morning.gif
└── top-cat.png
2 directories, 2 files