Automatic SSL with Let's Encrypt & Nginx
Tags: docker, security, architecture, tutorial
Published: 2020-02-13 14:34:11

_See update summary at bottom of post for changelog._

Note: December 2020 saw the release of v2 of the `letsencrypt-nginx-proxy-companion` project. I've updated this article to reflect that but will leave the old v1 code in the footer. If you need to upgrade your existing machines in situ, please refer to the [nginx-proxy/docker-letsencrypt-nginx-proxy-companion](https://github.com/nginx-proxy/docker-letsencrypt-nginx-proxy-companion) repository.

----

Since 2016, certificate authority Let's Encrypt have offered free SSL/TLS certificates in a bid to make encrypted communications on the web ubiquitous. If you've ever bought a certificate, you'll know they're usually quite expensive, the process for verifying them is a pain in the gluteus maximus, and then they expire while you're on holiday causing an outage.

With Let's Encrypt, all of these problems fade away, thanks to the Automated Certificate Management Environment (ACME) protocol that enables you to automate of the verification and deployment of certificates, saving you money and time. ACME is an interesting topic in it's own right, and you can read more about the various verification methods (called challenges) [here](https://letsencrypt.org/docs/challenge-types/), but today I'm going to show you how to easily setup a reverse proxy with automagical certificate generation, verification, and deployment.

The first thing we're going to do is create a [user defined bridge network](https://docs.docker.com/network/bridge/) called `service-network`. I'm bad at naming things but this seems applicable.

```
docker network create --subnet 10.10.0.0/24 service-network
```

![Fig A](https://dev-to-uploads.s3.amazonaws.com/i/gr0zmlvqurzgisagb1pq.png)

Next, we'll setup a reverse proxy. A reverse proxy simply accepts requests and proxies them onto another service based on routing rules such as which hostnames should go to which service containers. I imagine it looks something a little bit like this:

![Reverse Proxy (as I imagine it)](https://dev-to-uploads.s3.amazonaws.com/i/c2200do7rwus153u181q.png)

We'll use an image by Jason Wilder, [jwilder/nginx-proxy](https://github.com/node-proxy/nginx-proxy). This is a well maintained project with a lot of documentation. We map the ports 80 and 443 into the container so that we can handle both HTTP and HTTPS connections. We have a number of volumes too, three are standard docker volumes, and one is the docker daemon UNIX socket.

You might notice that I often use long-form arguments in scripts. While we could easily save space and have this on one line, it doesn't help others who may have to maintain scripts in the future.

```
docker run \
  --detach \
  --restart always \
  --publish 80:80 \
  --publish 443:443 \
  --name nginx-proxy \
  --network service-network \
  --volume /var/run/docker.sock:/tmp/docker.sock:ro \
  --volume nginx-certs:/etc/nginx/certs \
  --volume nginx-vhost:/etc/nginx/vhost.d \
  --volume nginx-html:/usr/share/nginx/html \
  jwilder/nginx-proxy
```

![Fig B](https://dev-to-uploads.s3.amazonaws.com/i/xmt3x6ztifhwyun8ok1q.png)

Ok, so now we have our reverse proxy, next we need to setup the Let's Encrypt companion, for which we'll be using Yves Blusseau's image [jrcs/letsencrypt-nginx-proxy-companion](https://github.com/node-proxy/docker-letsencrypt-nginx-proxy-companion). I've been using this flawlessly now for almost a year.

We map the same volumes to this container, though no ports are published. We set the `NGINX_PROXY_CONTAINER` environment variable to match the name of our proxy container, and that's about it. This container will run a process whenever new service containers are detected, generating certificates and keeping them up to date.

```
docker run \
  --detach \
  --restart always \
  --name nginx-proxy-letsencrypt \
  --network service-network \
  --volumes-from nginx-proxy \
  --volume /var/run/docker.sock:/var/run/docker.sock:ro \
  --volume /etc/acme.sh \
  --env "DEFAULT_EMAIL=mail@yourdomain.tld" \
  jrcs/letsencrypt-nginx-proxy-companion
```

![Fig C](https://dev-to-uploads.s3.amazonaws.com/i/cu7e9v9gmuwdrilgo50r.png)

Finally, it's time to add a service container. We'll use the `tutum/hello-world` image, quite a popular one for testing. For this we're going to need a hostname with the DNS configured. We'll pretend to use `hello-world.example.com` and pretend that we've setup an `A` record pointing to the IP address of this server.

```
docker run \
  --detach \
  --restart always \
  --name hello-world \
  --network service-network \
  --env VIRTUAL_HOST=hello-world.example.com \
  --env LETSENCRYPT_HOST=hello-world.example.com \
  --env LETSENCRYPT_EMAIL="youremail@example.com" \
  tutum/hello-world
```

![Fig D](https://dev-to-uploads.s3.amazonaws.com/i/texet0ds25wdv3er9vxy.png)

So let's take a look at what's going on here. We set up a proxy container which listens on ports 80 and 443. We then set up an ACME certificate container which will manage certs for us. Then we created a hello world container. We set the environment variable `VIRTUAL_HOST` to our hostname, and this is picked up by the proxy in order to route requests through to this container. The requests are routed through our user defined bridge `service-network`. We also set the environment variables `LETSENCRYPT_HOST` and `LETSENCRYPT_EMAIL` which are picked up by the ACME container and used when acquiring the certificate. FYI, the two hostnames will always have to match (`VIRTUAL_HOST` and `LETSENCRYPT_HOST`).

All we have to do is add these three variables to a container, and it'll be detected by the proxy and ACME containers and in short order, it'll work.

Now a few things to note. Port discovery — how does the proxy know which port to use? The hello-world image we use exposes a port in the Dockerfile with `EXPOSE 80`. This always takes precedence, so if the image has an exposed port, this will be used. But if your Dockerfile doesn't define an exposed port, or if you perhaps configure the port at runtime with an environment variable, e.g. `HTTP_PORT=8000`, then you can use the `--expose` argument to let the proxy know which port to use. If there are multiple ports available, you can specify which to use with the environment variable `VIRTUAL_PORT`.

Just to reiterate, Dockerfile `EXPOSE` takes precedence over `--expose` argument.

So now, when you hit `https://hello-world.example.com`, the DNS server returns an A record with your public IP, the browser then connects to this IP address on port 443 and in turn, the host routes that connection through to the `nginx-proxy` container. This terminates the SSL and proxies the request through to the `hello-world` container as a plain HTTP request.

![Fig E](https://dev-to-uploads.s3.amazonaws.com/i/mrjiz2gamxqox9fwzvbp.png)

Finally, there is another thing we can do. The proxy handles upgrading from HTTP to HTTPS, which is great, but sometimes you want to handle www/apex domain redirects. You can configure this in some domain registrar control panels, but then you end up with a different IP address for your hostname.

There is a better solution, and this time the image we'll use this time is actually one of mine, [adamkdean/redirect](https://github.com/adamkdean/redirect).

The way it works is super simple. You simply setup another container with the `VIRTUAL_HOST` set to the domain you want _to redirect away from_ and configure it's destination. Take for example we have `example.com` and we want it to always redirect to `www.example.com` because we love the www.


We have our main image like so, bound to `www.example.com`.

```
docker run \
  --detach \
  --restart always \
  --name example-website \
  --network service-network \
  --env VIRTUAL_HOST=www.example.com \
  example/website
```

We then create the redirect companion container, bound to `example.com`, with the environment variable `REDIRECT_LOCATION` being set to our preferred destination and `REDIRECT_STATUS_CODE` set as applicable.

```
docker run \
  --detach \
  --restart always \
  --name example-redirect \
  --network service-network \
  --env VIRTUAL_HOST=example.com \
  --env REDIRECT_LOCATION="http://www.example.com" \
  --env REDIRECT_STATUS_CODE=301 \
  adamkdean/redirect
```

What happens now is requests for `example.com` hit this redirect container, which responds with `REDIRECT_STATUS_CODE` and the `REDIRECT_LOCATION`.

We can of course use Let's Encrypt with these.

```
docker run \
  --detach \
  --restart always \
  --name example-website \
  --network service-network \
  --env VIRTUAL_HOST=www.example.com \
  --env LETSENCRYPT_HOST=www.example.com \
  --env LETSENCRYPT_EMAIL="youremail@example.com" \
  example/website

docker run \
  --detach \
  --restart always \
  --name example-redirect \
  --network service-network \
  --env VIRTUAL_HOST=example.com \
  --env LETSENCRYPT_HOST=example.com \
  --env LETSENCRYPT_EMAIL="youremail@example.com" \
  --env REDIRECT_LOCATION="https://www.example.com" \
  --env REDIRECT_STATUS_CODE=301 \
  adamkdean/redirect
```

In this case, the initial request for `example.com` hits the proxy, which terminates the SSL and proxies it through to the `example-redirect` container, which responds with a 301 to `www.example.com`. The next request which is now for `www.example.com` hits the proxy and is proxied through to the `example-website` container, something like this:

![Fig F](https://dev-to-uploads.s3.amazonaws.com/i/0mc7ybhn4qe68d9crym0.png)

I hope this helps you. This setup can work for single sites or for a number of sites. I use this in situations where setting up a large container platform is a little bit overkill (kubernetes for a blog is fine, right guys?)

It's super easy to update and deploy, and having used it for over a year now, it's working great. Thanks for reading.

----

Update (Feb 21, 2020): as requested, here is a `docker-compose.yml` version.

```
version: "3"

services:
  web:
    image: example/website
    expose:
     - 8000
    environment:
      HTTP_PORT: 8000
      VIRTUAL_HOST: www.example.com
      LETSENCRYPT_HOST: www.example.com
      LETSENCRYPT_EMAIL: "example@example.com"
    networks:
      service_network:

  web-redirect:
    image: adamkdean/redirect
    environment:
      VIRTUAL_HOST: example.com
      LETSENCRYPT_HOST: example.com
      LETSENCRYPT_EMAIL: "example@example.com"
      REDIRECT_LOCATION: "https://www.example.com"
    networks:
      service_network:

  nginx-proxy:
    image: jwilder/nginx-proxy
    ports:
      - 80:80
      - 443:443
    container_name: nginx-proxy
    networks:
      service_network:
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - nginx-certs:/etc/nginx/certs
      - nginx-vhost:/etc/nginx/vhost.d
      - nginx-html:/usr/share/nginx/html

  nginx-proxy-letsencrypt:
    image: jrcs/letsencrypt-nginx-proxy-companion
    environment:
      NGINX_PROXY_CONTAINER: "nginx-proxy"
    networks:
      service_network:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - nginx-certs:/etc/nginx/certs
      - nginx-vhost:/etc/nginx/vhost.d
      - nginx-html:/usr/share/nginx/html

networks:
  service_network:

volumes:
  nginx-certs:
  nginx-vhost:
  nginx-html:
```

----

Update (Feb 28, 2020): 

I realised that I made a mistake when talking about `VIRTUAL_PORT`. I've updated the document but just to clarify, you tell the proxy which port to use with the `EXPOSE` command in a Dockerfile and the `--expose` argument on the Docker command line interface. If there are multiple ports exposed, you can then use the `VIRTUAL_PORT` environment variable to signal _which_ exposed port to use.

Sorry about the mix up!

----

Update (Apr 22, 2020): 

Added some missing backslashes to the secure redirect snippets. Oops!

----

Update (Dec 11, 2020):

The v1 code for letsencrypt-nginx-proxy-companion.

```
docker run \
  --detach \
  --restart always \
  --name nginx-proxy-letsencrypt \
  --network service-network \
  --volume /var/run/docker.sock:/var/run/docker.sock:ro \
  --volume nginx-certs:/etc/nginx/certs \
  --volume nginx-vhost:/etc/nginx/vhost.d \
  --volume nginx-html:/usr/share/nginx/html \
  --env NGINX_PROXY_CONTAINER="nginx-proxy" \
  jrcs/letsencrypt-nginx-proxy-companion:v1.13.1
```


----

If you enjoyed this article, you might enjoy my next one [Debugging Docker Containers](https://dev.to/adamkdean/debugging-docker-containers-17fh), where we delve into a few ways that you can work out just what is going on inside these black boxes we call containers.

_A note on injecting docker.sock: the docker daemon UNIX socket (/var/run/docker.sock) gives access to docker, which in other words, is root access. Be sure you know what you're giving this too whenever you're running third party images._