Docker Compose

Usage with Docker Compose

As stated by its repository, Docker Compose is a tool for defining and running multi-container Docker applications using a single Compose file. This Wiki page is not meant to be a definitive reference on how to run nginx-proxy and letsencrypt-nginx-proxy-companion with Docker Compose, as the number of possible setups is quite extensive and they can't be all covered.

Before your start

Be sure to be familiar with both the basic and avanced non compose setups, and Docker Compose usage.

The name nginx-proxy in this wiki will refer to both the nginx-proxy in a two containers setup and nginx in a three containers setup.

The name letsencrypt will refer to letsencrypt-nginx-proxy-companion.

Getting containers IDs

For letsencrypt-nginx-proxy-companion to work properly, it needs to know the ID of the nginx-proxy container (in both setups), plus the ID of the docker-gen container in a three container setup.

There are three methods to inform the letsencrypt container of the nginx-proxy container ID:

• label method: add the label com.github.jrcs.letsencrypt_nginx_proxy_companion.nginx_proxyto the nginx-proxy container.

• environment variable method: assign a fixed name to the nginx-proxy container with container_name: and set the environment variable NGINX_PROXY_CONTAINER to this name on the letsencrypt container.

• volumes_from method (only available on compose file version 2). Using this method, the letsencrypt container will get the nginx-proxy container ID from the volumes it got using the volumes_from option.

And two methods to inform the letsencrypt container of the docker-gen container ID:

• Label method: add the label com.github.jrcs.letsencrypt_nginx_proxy_companion.docker_gen to the docker-gen container.

• Environment variable method: assign a fixed name to the docker-gen container with container_name: and set the environment variable NGINX_DOCKER_GEN_CONTAINER to this name on the letsencrypt container.

The methods for each container are sorted by order of precedence, meaning that if you use both the label and the volumes_from method, the ID of the nginx-proxy container that will be used will be the one found using the label. There is no point in using more than one method at a time for either the nginx-proxy or docker-gen container beside potentially confusing yourself.

The advantage the label methods have over the environment variable (and volumes_from) methods is enabling the use of the letsencrypt in environments where containers names are dynamic, like in Swarm Mode or in Docker Cloud. Howhever if you intend to do so, as upstream docker-gen lacks the ability to identify containers from labels, you'll need both to use the three container setup and to replace jwilder/docker-gen with a fork that has this ability like herlderco/docker-gen. Be advised that for now, this works to a very limited extent (everything has to be on the same node).

Examples

The following examples are minimal, clean starting points using compose file version 2. Again they are not intended as a definitive reference.

The use of named containers and volume is not required but helps keeping everything clear and organized.

Two containers example

version: '2'

services:
  nginx-proxy:
    image: jwilder/nginx-proxy
    container_name: nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - conf:/etc/nginx/conf.d
      - vhost:/etc/nginx/vhost.d
      - html:/usr/share/nginx/html
      - dhparam:/etc/nginx/dhparam
      - certs:/etc/nginx/certs:ro
      - /var/run/docker.sock:/tmp/docker.sock:ro
    network_mode: bridge

  letsencrypt:
    image: jrcs/letsencrypt-nginx-proxy-companion
    container_name: nginx-proxy-le
    volumes_from:
      - nginx-proxy
    volumes:
      - certs:/etc/nginx/certs:rw
      - /var/run/docker.sock:/var/run/docker.sock:ro
    network_mode: bridge

volumes:
  conf:
  vhost:
  html:
  dhparam:
  certs:

Note: nginx-proxy Dockerfile create a volume for /etc/nginx/dhparam, so this compose file include it as a named volume instead of letting it be created anyway as an anonymous volume.

Three containers example

version: '2'

services:
  nginx-proxy:
    image: nginx:alpine
    container_name: nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - conf:/etc/nginx/conf.d
      - vhost:/etc/nginx/vhost.d
      - html:/usr/share/nginx/html
      - certs:/etc/nginx/certs:ro
    network_mode: bridge

  docker-gen:
    image: jwilder/docker-gen
    container_name: nginx-proxy-gen
    command: -notify-sighup nginx-proxy -watch /etc/docker-gen/templates/nginx.tmpl /etc/nginx/conf.d/default.conf
    volumes_from:
      - nginx-proxy
    volumes:
      - /path/to/nginx.tmpl:/etc/docker-gen/templates/nginx.tmpl:ro
      - /var/run/docker.sock:/tmp/docker.sock:ro
    labels:
      - "com.github.jrcs.letsencrypt_nginx_proxy_companion.docker_gen"
    network_mode: bridge

  letsencrypt:
    image: jrcs/letsencrypt-nginx-proxy-companion
    container_name: nginx-proxy-le
    volumes_from:
      - nginx-proxy
    volumes:
      - certs:/etc/nginx/certs:rw
      - /var/run/docker.sock:/var/run/docker.sock:ro
    network_mode: bridge

volumes:
  conf:
  vhost:
  html:
  certs:

Note: don't forget to replace /path/to/nginx.tmpl with the actual path to the nginx.tmpl file you downloaded.

Other (external) examples

If you want other examples how to use this container with Docker Compose, look at:

• Nicolas Duchon's Examples - with automated testing
• Evert Ramos's Examples - using docker-compose version '3'
• Karl Fathi's Examples
• More examples from Karl
• George Ilyes' Examples
• Dmitry's simple docker-compose example
• Radek's docker-compose jenkins example