zedtux/nginx-proxy repository overview

nginx-proxy sets up a container running nginx and docker-gen⁠. docker-gen generate reverse proxy configs for nginx and reloads nginx when containers they are started and stopped.

See Automated Nginx Reverse Proxy for Docker⁠ for why you might want to use this.

This fork is from jwilder⁠.

⁠About this fork

This fork is adding the following:

• Use the official Nginx Docker image (Stable version for production)
• Hidding the Nginx version number (server_tokens)
• Adding the possibility to define change the default size of uploads (client_max_body_size)
• Allow to mount a volume to /etc/nginx/sites-enabled/ in order to check the genenrated Nginx configuration file
• Adding TLS (SSL) support
• Basic Auth

You can fetch the image from https://registry.hub.docker.com/u/zedtux/nginx-proxy/⁠.

⁠The original features

⁠Usage

To run it:

$ docker run -d -p 80:80 -v /var/run/docker.sock:/tmp/docker.sock zedtux/nginx-proxy

Then start any containers you want proxied with an env var VIRTUAL_HOST=subdomain.youdomain.com

$ docker run -e VIRTUAL_HOST=foo.bar.com  ...

Provided your DNS is setup to forward foo.bar.com to the a host running nginx-proxy, the request will be routed to a container with the VIRTUAL_HOST env var set.

⁠Multiple Ports

If your container exposes multiple ports, nginx-proxy will default to the service running on port 80. If you need to specify a different port, you can set a VIRTUAL_PORT env var to select a different one. If your container only exposes one port and it has a VIRTUAL_HOST env var set, that port will be selected.

⁠Multiple Hosts

If you need to support multipe virtual hosts for a container, you can separate each entry with commas. For example, foo.bar.com,baz.bar.com,bar.com and each host will be setup the same.

⁠Separate Containers

nginx-proxy can also be run as two separate containers using the jwilder/docker-gen⁠ image and the official nginx⁠ image.

You may want to do this to prevent having the docker socket bound to a publicly exposed container service.

To run nginx proxy as a separate container you'll need to have nginx.tmpl⁠ on your host system.

First start nginx with a volume:

$ docker run -d -p 80:80 --name nginx -v /tmp/nginx:/etc/nginx/conf.d -t nginx

Then start the docker-gen container with the shared volume and template:

$ docker run --volumes-from nginx \
    -v /var/run/docker.sock:/tmp/docker.sock \
    -v $(pwd):/etc/docker-gen/templates \
    -t docker-gen -notify-sighup nginx -watch --only-published /etc/docker-gen/templates/nginx.tmpl /etc/nginx/conf.d/default.conf

Finally, start your containers with VIRTUAL_HOST environment variables.

$ docker run -e VIRTUAL_HOST=foo.bar.com  ...

⁠TLS (SSL) Support

In the case you have a TLS (or the SSL) certificate you can easily use it with nginx.

Create a directory on your server where you will upload the .crt and .key files to be used:

$ mkdir /etc/docker/my-app/ssl/
$ cp ~/my-app.* /etc/docker/my-app/ssl/
$ ls -al /etc/docker/my-app/ssl/
total 4
-rw-r--r-- 4 root root 4096 Nov 15 18:01 my-app.crt
-rw-r--r-- 4 root root 4096 Nov 15 18:01 my-app.key

Run the nginx image with a volume to this folder and with the port 443:

$ docker run -d -p 80:80 -p 443:443 -v /etc/docker/my-app/ssl/:/etc/nginx/ssl/ -v /var/run/docker.sock:/tmp/docker.sock zedtux/nginx-proxy

Now when you will start you application, just set the variable SSL_FILENAME:

$ docker run -e VIRTUAL_HOST=my-app.domain.tld -e SSL_FILENAME=my-app username/imagename

You should then be able to access https://my-app.domain.tld/⁠.

⁠Basic Auth

Basic Auth coupled with HTTPS can be a simple way to secure the access to an URL.

First of all prepare a folder where to store the .htpasswd files and generate one:

$ mkdir /etc/docker/nginx/htpasswd/
$ htpasswd -c /etc/docker/nginx/htpasswd/my-app.htpasswd zedtux
New password:
Re-type new password:
Adding password for user zedtux

Run the nginx image with a volume in order to mount this folder in the nginx container:

$ docker run -d -p 80:80 -p 443:443 -v /etc/docker/nginx/htpasswd/:/etc/nginx/htpasswd/ -v /var/run/docker.sock:/tmp/docker.sock zedtux/nginx-proxy

Now start your application container passing the HTPASSWD_FILENAME variable:

$ docker run -e VIRTUAL_HOST=my-app.domain.ltd -e HTPASSWD_FILENAME=my-app username/imagename

Accessing http://my-app.domain.ltd/⁠ should ask you for a login and password.

⁠Docker registry

The Docker registry requires to have 2 URLs without the Basic Auth in order to work properly. You just have to define the variable DOCKER_REGISTRY in order to fix it:

$ docker run -d -e VIRTUAL_HOST=registry.domain.tld -e HTPASSWD_FILENAME=registry -e DOCKER_REGISTRY=true registry