Doc updates for V3 Docker compose?

[SuperRoach]

trafficstars

There are a lot of wildly varying examples on the web for using this with Docker compose v3, are there any thoughts about updating the docs to support it?

[buchdag]

I could update the doc with the Docker compose v3 files used here if that suits you : https://github.com/buchdag/letsencrypt-nginx-proxy-companion-compose

edit: wrong URL

[SuperRoach]

I've added another barebones example using the v2 syntax if that helps for now too: https://gitlab.com/SuperRoach/barebones-ssl-letsencrypt

The doc mention in your edit is good that it explains what the tag was used for and stuff. It'd probably help to be a self contained example instead of only referencing the container you want to add.

[buchdag]

It'd probably help to be a self contained example instead of only referencing the container you want to add.

I didn't get that part 😶

[SuperRoach]

Sorry, by that I mean your example on there only illustrates what the container we should add looks like - you could give us a sample or two of how it would look like (the connected volumes for example) with a self contained piece of code that could live in a docker-compose.yml file.

In the issue https://github.com/nginx-proxy/docker-letsencrypt-nginx-proxy-companion/issues/651 , the main problem was interpreting where the volumes go as an example, and the sample posted is difficult to use in isolation (due to the amount of environment vars in it)

[buchdag]

Okay, I think I got it this time. I'll have to think about it, I don't wan't ending up merging https://github.com/buchdag/letsencrypt-nginx-proxy-companion-compose into this repo.

I know that @JrCs wasn't really hot on adding Docker compose reference files probably out of fear of having to troubleshoot people use of Docker compose rather than actual issue with the container. I must admit that I find myself having to do this more often than I'd like to (like in #651).

If I go this way and further develop the Docker compose docs I will probably have to add a note at some point about not providing support for any deviation from those reference examples.

[polarathene]

If it's helpful, I wrote a docker-compose example in docs here.

It needs a little revision, such as dropping the now no longer necessary dhparam volume, but should otherwise be useful?

Copy of current linked example

version: '3.8'
services:
  # Add the following `environment` and `volumes` to your existing `mailserver` service:
  mailserver:
    environment:
      # SSL_TYPE:         Uses the `letsencrypt` method to find mounted certificates.
      # VIRTUAL_HOST:     The FQDN that `nginx-proxy` will configure itself to handle for HTTP[S] connections.
      # LETSENCRYPT_HOST: The FQDN for a certificate that `acme-companion` will provision and renew.
      - SSL_TYPE=letsencrypt
      - VIRTUAL_HOST=mail.example.com
      - LETSENCRYPT_HOST=mail.example.com
    volumes:
      - ./docker-data/acme-companion/certs/:/etc/letsencrypt/live/:ro

  # If you don't yet have your own `nginx-proxy` and `acme-companion` setup,
  # here is an example you can use:
  reverse-proxy:
    image: nginxproxy/nginx-proxy
    container_name: nginx-proxy
    restart: always
    ports:
      # Port  80: Required for HTTP-01 challenges to `acme-companion`.
      # Port 443: Only required for containers that need access over HTTPS. TLS-ALPN-01 challenge not supported.
      - "80:80"
      - "443:443"
    volumes:
      # `certs/`:      Managed by the `acme-companion` container (_read-only_).
      # `docker.sock`: Required to interact with containers via the Docker API.
      # `dhparam`:     A named data volume to prevent `nginx-proxy` creating an anonymous volume each time.
      - ./docker-data/nginx-proxy/html/:/usr/share/nginx/html/
      - ./docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/
      - ./docker-data/acme-companion/certs/:/etc/nginx/certs/:ro
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - dhparam:/etc/nginx/dhparam

  acme-companion:
    image: nginxproxy/acme-companion
    container_name: nginx-proxy-acme
    restart: always
    environment:
      # Only docker-compose v2 supports: `volumes_from: [nginx-proxy]`,
      # reference the _reverse-proxy_ `container_name` here:
      - NGINX_PROXY_CONTAINER=nginx-proxy
    volumes:
      # `html/`:       Write ACME HTTP-01 challenge files that `nginx-proxy` will serve.
      # `vhost.d/`:    To enable web access via `nginx-proxy` to HTTP-01 challenge files.
      # `certs/`:      To store certificates and private keys.
      # `acme-state/`: To persist config and state for the ACME provisioner (`acme.sh`).
      # `docker.sock`: Required to interact with containers via the Docker API.
      - ./docker-data/nginx-proxy/html/:/usr/share/nginx/html/
      - ./docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/
      - ./docker-data/acme-companion/certs/:/etc/nginx/certs/:rw
      - ./docker-data/acme-companion/acme-state/:/etc/acme.sh/
      - /var/run/docker.sock:/var/run/docker.sock:ro

# Once `nginx-proxy` fixes their Dockerfile, this named data volume can be removed from docs.
# Users can opt for a local bind mount volume like all others if they prefer, but this volume
# is only intended to be temporary.
volumes:
  dhparam:

---

Note that the mailserver container is mounting the certs volume as it doesn't go through nginx-proxy for TLS due to SMTP ports (25, 587, 465, etc) and manages that itself just with acme-companion providing the certs.

The example is for users with existing nginx-proxy setup to reference, but we also advise alternative approach with acme-companion for provisioning standalone certs too.

Feel free to copy and adapt to your own docs if you like, or migrate to generating and serving docs in the same manner (Github Pages via Github Actions building from markdown files).