A while ago, I wrote an article titled “Nginx and Let’s Encrypt in Less Than 5 Minutes”. It quickly became my most popular post ever, with thousands of claps and hundreds of forks and stars on GitHub.
My original approach included a script that needed to be run once for each deployment. It’s effective, simple — but a little clumsy. So I kept wondering: What if there is an even easier way to set up Let’s Encrypt with docker-compose?
I like keeping things simple. This is why I tend to avoid unnecessary dependencies in my projects. You certainly won’t find me using packages like is-odd
or the infamous left-pad
. So when my colleague Christian suggested adding a dependency “just” for managing HTTPS certificates, I wasn’t a big fan. Why not just use my script, I wondered. But I gave it a try and never looked back.
So here it is, my new best solution for securing your Docker app with an HTTPS certificate from Let’s Encrypt. This article is going to use docker-compose but you could use the same technique with Kubernetes or “pure” Docker.
Before we continue, here is a short but shameless plug: I occasionally write about deployment best practices, JavaScript and Elixir. If you’d like to keep up, please sign up to my 100% spam-free newsletter.
Traefik
The Unix Principle
Do One Thing and Do It Well. This is one of the main tenants of Unix philosophy. Following this principle, let’s ask the question: what do we need when we want to “Add Let’s Encrypt to a Docker App”? We want to request and renew HTTPS certificates, we want to terminate TLS (HTTPS) connections and, finally, pass the connection on to our containerized application. You might argue that this is actually four different things, but for our purposes, it’s the combination of these features that matters. Fortunately, there is a tool that implements this very set of features: Traefik.
Traefik (pronounced traffic) is a modern HTTP reverse proxy and load balancer that […] configures itself automatically and dynamically.
You probably think of Nginx or Apache when they hear the term reverse proxy. Many modern web frameworks come with their own HTTP server (e.g. Express in Node.js, Puma in Ruby, Plug in Elixir, or Tomcat in Java). But more often than not, that server isn’t exposed directly to your users. Instead, a reverse proxy terminates TLS connections and then passes on simple HTTP requests to your app.
This means, Traefik can take the role of Nginx if you’re running an application with a web server. But Traefik can also be a reverse proxy for Nginx, taking care of routing and HTTPS.
Automatic configuration
Now to the interesting part: The docs say Traefik configures itself automatically. How is that even possible? The answer is Docker Object Labels.
Every Docker container can be assigned one or several labels. Once you’ve got Traefik running, making a service available on a specific host name is as simple as assigning it the following label: traefik.http.routers.my-app.rule=Host(`example.com`)
.
Traefik processes all Docker labels in real time. This makes sure your routes are always configured according to the containers you have running. And since Traefik supports Let’s Encrypt by default, your container will receive an HTTPS certificate almost instantly.
Setting up Let’s Encrypt Certificates For Your Docker App With Traefik
Setting Up Traefik
Before we get started, we need to create the Traefik config files. Traefik distinguishes between two types of configuration: static configuration is loaded at startup and describes the Traefik instance. dynamic configuration is loaded at runtime and describes services and middlewares.
Start by creating a folder name traefik
that will contain our configuration.
Here’s what we want to configure in the static configuration, traefik/traefik.toml
:
- An entry point
http
on port 80 - An entry point
https
at port 443 - A certificate resolver
lets-encrypt
to automatically retrieve certificates from Let’s Encrypt via the ACME protocol
Note: Setting
providers.docker.exposedByDefault
tofalse
makes sure we don’t accidentally expose containers and need to explicitly enable Traefik for each container we want to use it with.
Make sure to insert a working email address in the configuration to get notified by Let’s Encrypt whenever there is a problem with your certificate.
In order to enforce HTTPS for our domains, we now need to add a router and a middleware to our dynamic configuration, traefik/dynamic/force-https.toml
:
Next, we need an empty file in which Traefik can store retrieved HTTPS certificates. Make sure to set restrictive rw-------
permissions or else Traefik refuses to use the file.
touch traefik/acme.json
chmod 600 traefik/acme.json
Finally, let’s create a docker-compose.yml
file that starts Traefik:
Configuring Your Container(s)
Now we’re ready to launch our own application! Add your app to docker-compose. Keep in mind that you’ll have to replace “my-app” with the actual name of your application and “example.com” with your actual domain.
Pro tip: If you need multiple domains for one container, you can use comma-separated values (e.g.
Host(`foo.bar`, `fizz.buzz`)
). And in case you need a lot of domains, you can use\
to break the expression into multiple lines.
Done!
Are we done already? Yes, we are!
As soon as you run docker-compose up
, Traefik and your application will start. Traefik will then immediately get a Let’s Encrypt certificate for your domain and you’ll be online, secured with HTTPS, in seconds. If only life could always be so easy.
Did you enjoy this article?
I occasionally write about deployment best practices, JavaScript and Elixir. If you’d like to keep up, sign up to my 100% spam-free newsletter.
You can also follow me on Twitter @pentacent_hq