Table of Contents

Mounts: configuration

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Mounts: configuration

All configuration in the container is loaded from /etc/nginx/config. Within that directory, NGINX will process files with the extension .conf. There are two things to note about this:

Files are read in the same order as they would be listed via the ls command. Unlike site-block configurations, the order of configuration files almost never matters since there cannot be duplication anyways.
If you want to disable a file containing settings, simply rename the file using a different extension – I usually use .conf.disabled. Then, you can restart the container (docker restart ab-nginx) and those settings will be ignored.

By default, the configuration directory is empty, meaning that only NGINX internal defaults are applied. In addition, the nginx.conf only loads the bare minimum options. As such, the configuration directory becomes both a powerful and simple way to set up NGINX as you want.

The easiest way to apply configurations are to group them thematically into files and place those files into a single directory which is bound to the container. Let’s do a quick example. I’ll make a few files to apply some global settings and save them all in ~/nginx/config for the sake of this example:

# buffers.conf
client_body_buffer_size 16k;
client_header_buffer_size 1k;
large_client_header_buffers 4 8k;
client_max_body_size 10M;

# staticContent.conf
sendfile on;
sendfile_max_chunk 1M;
tcp_nopush on;
tcp_nodelay on;

# timeouts.conf
client_body_timeout 30s;
client_header_timeout 15s;
send_timeout 30s;
keepalive_timeout 75s;
reset_timedout_connection on;

# proxyTimeouts.conf
proxy_connect_timeout 30s;
proxy_read_timeout 30s;
proxy_send_timeout 60s;

# proxyLongTimeouts.conf.disabled
proxy_connect_timeout 30s;
proxy_read_timeout 600s;
proxy_send_timeout 600s;

Now, let’s go ahead and mount these configurations in the container, making sure that they are readable by UID 8080:

# set permissions (only allow root and container to access configurations)
chown -R root:8080 ~/nginx/config
chmod 750 ~/nginx/config
chmod 640 ~/nginx/config/*

# start container with our configurations mounted
docker run -d --name ab-nginx --restart unless-stopped \
  -p 80:80 \
  -v /var/www:/usr/share/nginx/html \
  -v ~/nginx/config:/etc/nginx/config:ro \
  asifbacchus/ab-nginx

In this example, I pretended that our configurations were sensitive and were previously only visible to root. So the first thing I did was change the permissions so that our container user, UID 8080, could read them but other users still cannot. This is for the sake of this contrived example, obviously permissions will depend entirely on your particular environment.

Also, you’ll note that I add:ro after sites and configuration mounts. This means ‘read-only’ in the container and is a security precaution. Simply put, it means the container cannot change the files in that mount. This is strictly optional and is dependant on your use-case.

Ok, so our container configurations are being used! That was easy. Let’s extend the example now. You’ll notice that one of the files that was mounted was proxyTimeouts.conf and another one was proxyLongTimeouts.conf.disabled. Why didn’t NGINX complain about duplicate settings? Because only files with the extension .conf are read and the second file has a different extension! What good is this? Well, let’s say that I’m using this container to test a reverse proxy in front of a docker registry. Those things require a very long timeout. However, I also run this container to test other things that are fine with a normal timeout. I do not have to delete configurations, I only have to rename files and I can switch between settings!

# all of this is on the *host*

# rename our files to activate the settings we want
cd ~/nginx/config
mv proxyTimeouts.conf proxyTimeouts.conf.disabled
mv proxyLongTimeouts.conf.disabled proxyLongTimeouts.conf

# restart the container to activate
docker restart ab-nginx

Now, maybe I realize I forgot to add a resolver… Let’s make a new configuration file and activate it in the container:

# resolver.conf
resolver
  1.1.1.1
  1.0.0.1;

# make sure permissions are set, just like before
chown root:8080 ~/nginx/config/resolver.conf
chmod 640 ~/nginx/config/resolver.conf

# restart the container
docker restart ab-nginx

Finally, you can of course remove a configuration just by deleting the corresponding file containing those settings and restarting the container. I trust, however, that does not need an example here.

I hope that overview has helped clear things up about mounting configurations. 99% of the time, this should be all you need.