nginx logo

When testing changes to your Nginx configuration for your staging or production (or any other remote) environments, one can encounter problems:

  • If the changes are made as part of a CI/CD pipeline, each change requires you to wait for the pipeline to build before testing. This waiting time will typically be minutes rather than seconds
  • Making the changes directly to the configuration files on the server means you can test your changes basically straight away. However,
    • If you have a load balancer directing traffic to more than one instance, you have to make the same change in several places
    • If you have a load balancer and your instances are in a private subnet, SSH-ing into those instances requires setting up a VPN
    • Changing files directly on a server is bad practice as there is no record of those changes. What happens if you would like to revert a mistake?

One way around this is to test your Nginx configuration changes locally (like you would with regular application code).

In this post we will show how to do this.


  • Docker; whilst you could download Nginx directly onto your machine, using Docker means you can easily:
    • Install and uninstall Nginx
    • Reset your Nginx configuration files
    • Run multiple Nginx processes at the same time
    • Change the port Nginx runs on
    • Change Nginx version…, etc.

Getting started

To run Nginx in a Docker container and serve requests on port 8000 on your machine,

docker run --interactive --tty --publish 8000:80 nginx bash

(if you are on macOS, you might have to start the Docker daemon first by clicking on an icon)

This command also SSHs you into the container.

In the container shell, check Nginx is installed

which nginx


and that it is running

service nginx status

[FAIL] nginx is not running ... failed!

As it is not running, start it

service nginx start; service nginx status

[ ok ] nginx is running.

Make a request to http://localhost:8000 in the browser. You should see the "Welcome to nginx!" page.

Similarly, in Python

import requests

r = requests.get('http://localhost:8000')

you should get back the HTML of the page and the response status code.

You should also see the relevant logs in the container shell - - [21/Oct/2019:17:53:21 +0000] "GET /favicon.ico HTTP/1.1" 404 555 "http://localhost:8000/" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.120 Safari/537.36" "-" - - [21/Oct/2019:17:54:51 +0000] "GET / HTTP/1.1" 200 612 "-" "python-requests/2.18.4" "-"

Changing the “Welcome to nginx” page

To make changes to the Nginx configuration, we will need to edit files inside the container shell.

By default, there is no text editor inside the container shell.

We will install Vim, but any text editor will do.

Inside the container shell,

  • apt-get update
  • apt-get install vim --yes

We can now use our text editor to have a look at the Nginx configuration

  • cd /etc/nginx/conf.d
  • vi default.conf

You should see the following configuration or similar

server {
    listen       80;
    server_name  localhost;

    #charset koi8-r;
    #access_log  /var/log/nginx/host.access.log  main;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;

    #error_page  404              /404.html;

    # redirect server error pages to the static page /50x.html
    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;

    # proxy the PHP scripts to Apache listening on
    #location ~ \.php$ {
    #    proxy_pass;

    # pass the PHP scripts to FastCGI server listening on
    #location ~ \.php$ {
    #    root           html;
    #    fastcgi_pass;
    #    fastcgi_index  index.php;
    #    fastcgi_param  SCRIPT_FILENAME  /scripts$fastcgi_script_name;
    #    include        fastcgi_params;

    # deny access to .htaccess files, if Apache's document root
    # concurs with nginx's one
    #location ~ /\.ht {
    #    deny  all;

As the web server document root is /usr/share/nginx/html, inside /usr/share/nginx/html is index.html.

Change index.html so that the title and header reads "Bienvenue a nginx!" instead of "Welcome to nginx!".

To let the changes take effect, restart Nginx

service nginx reload

When you make a request to http://localhost:8000, you should see the new title and header.

Changing the Nginx configuration to prevent web cache poisoning

Web cache poisoning:

Web cache poisoning is geared towards sending a request that causes a harmful response that then gets saved in the cache and served to other users.

One method of web cache poisoning starts with spoofing the host in the request header.

For example, if your website is written in Django, Django uses the host in the request header when generating its URLs.

Thus if you have a Django URL /my-login, and the host in the request header is (although your site’s domain is, if Django internally makes requests to /my-login, these requests will go to and not then sends a harmful response that gets saved in the cache and served to other users. Web cache poisoning complete!

To mitigate this security risk, Django has an ALLOWED_HOSTS setting.

By setting


Django will only make requests to If an attacker sends a request with host, it throws a SuspiciousOperation error and returns a Bad request response with status code 400.

One of the drawbacks of the above is that it usually leads to noisy logging due to bots checking for vulnerabilities in your site.

Assuming your website is served by Nginx, one way around this is to configure Nginx so that any request with a host in the header not equal to is given a 4xx error response (ideally, the error code should capture just this issue as otherwise all you have done is transferred your noisy logging problem from Django to Nginx).

Let’s now test this workaround locally.

Making a spoof request in Python

import requests

url = 'http://localhost:8000'
headers = {'host': ''}
r = requests.get(url, headers=headers)

The response is exactly the same as before, despite having

server_name localhost;

in our server block in default.conf and the host in the request header being

Changing the Nginx configuration

So why did we get a 200 response despite the host in the Nginx configuration not matching the host sent in the request?

This is because if Nginx finds no matching server blocks, it uses the first server block.

To check this, let’s add

server {
    listen 80;
    return 403 "Your request is forbidden";

to the end of default.conf. To make the changes take effect,

service nginx reload

Now, making the same request in Python, we get a response status code of 403 with content

'Your request is forbidden'

However, if we spoof the header with a host different to, we will get a 200 again.

Actually, all we have to do is add

server {
    listen 80;
    return 403 "Your request is forbidden";

to the start of default.conf.

Now, whenever the host in the header is not equal to localhost, a 403 is returned.

Although functionally it makes no difference, the convention is to add default_server to the block, i.e. to have

server {
    listen 80 default_server;
    return 403 "Your request is forbidden";

at the start of default.conf.

Now your Nginx configuration is setup to prevent web cache poisoning!