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

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

Usage

To run it:

docker run --detach \
    --name nginx-proxy \
    --publish 80:80 \
    --volume /var/run/docker.sock:/tmp/docker.sock:ro \
    pinidh/nginx-proxy

Then start any containers (here an nginx container) you want proxied with an env var VIRTUAL_HOST=subdomain.yourdomain.com

docker run --detach \
    --name your-proxied-app \
    --env VIRTUAL_HOST=foo.bar.com \
    nginx

Provided your DNS is setup to resolve foo.bar.com to the host running nginx-proxy, a request to http://foo.bar.com will then be routed to a container with the VIRTUAL_HOST env var set to foo.bar.com (in this case, the your-proxied-app container).

The containers being proxied must :

• expose the port to be proxied, either by using the EXPOSE directive in their Dockerfile or by using the --expose flag to docker run or docker create.
• share at least one Docker network with the nginx-proxy container: by default, if you don't pass the --net flag when your nginx-proxy container is created, it will only be attached to the default bridge network. This means that it will not be able to connect to containers on networks other than bridge.

Note: providing a port number in VIRTUAL_HOST is suported with syntax <virtual_hostname>:<port_number>. The use case for this syntax is adressing different ports of the same container via different virtual hosts. For these hosts the variable VIRTUAL_PORT - if defined - is ignored and the port provided with the virtual host name is used instead. VIRTUAL_PATH and VIRTUAL_DEST apply though.

Image variants

The nginx-proxy images are available in two flavors.

Debian based version

This image is based on the nginx:mainline image, itself based on the debian slim image.

docker pull pinidh/nginx-proxy

Alpine based version (-alpine suffix)

This image is based on the nginx:alpine image.

docker pull pinidh/nginx-proxy:alpine

⚠️ a note on latest and alpine:

It is not recommended to use the latest (nginxproxy/nginx-proxy, nginxproxy/nginx-proxy:latest) or alpine (nginxproxy/nginx-proxy:alpine) tag for production setups.

Those tags point to the latest commit in the main branch. They do not carry any promise of stability, and using them will probably put your nginx-proxy setup at risk of experiencing uncontrolled updates to non backward compatible versions (or versions with breaking changes). You should always specify the version you want to use explicitly to ensure your setup doesn't break when the image is updated.

Additional documentation

Please check the docs section.