Skip to content

Instantly share code, notes, and snippets.

Created April 22, 2020 07:47
Show Gist options
  • Save voronenko-p/fbd4bd0d05fd3ff65a788d42f444bb37 to your computer and use it in GitHub Desktop.
Save voronenko-p/fbd4bd0d05fd3ff65a788d42f444bb37 to your computer and use it in GitHub Desktop.

Unobtrusive local development with traefik2, docker and letsencrypt

When it comes to developing sites that use subdomains, this can be a challenging or boring task to set up in development because localhost isn’t a fully qualified domain name. You can’t just goto example.localhost. You either constantly edit /etc/hosts or setting up some dnsmasq in your local network.

So far most often used solutions by myself were is a free service that resolves itself along with all subdomains to localhost, and similar to it service which allows to code ip address to resolve into domain name, and thus allowing to generate letsencrypt certificate to mentioned domain.

This played good for a decade, but as more and more of mine clients were moving to pull request reviews and choosing docker or kubernetes as a platform in parallel, I found myself more and more limited with classic solutions above.

What I wanted last year - is reproducible scenario to implement own, branded local development environment that I can easily reproduce on a remote server to implement pull request reviews scenarios, supporting some reasonable perks like green seal certificates, some troubleshouting capabilities and so on.

Let's take a look on a approach I am using now for clients using dockerized applications (either local or swarm)

Choosing components for the solution

Cooking components:

a) docker - classic or in swarm mode. (On my work notebook I have docker in swarm mode, it does not stop it from be used as a standalone docker environment too)

b) traefik2 , and it's official docker image. Traefik is an open-source Edge Router that makes publishing your services a fun and easy experience. It receives requests on behalf of your system and finds out which components are responsible for handling them. Kind of interest for me are two backends - docker and kubernetes.

c) Development subdomain. For nicely working solution we need to dedicate some subdomain for development, for example: * - resolving to localhost, or * - some wildcard domain pointing to your staging server.

d) Wildard certificate from letsencrypt to organize green seal certificate. Althouth on remote box traefik might take care on obtaining green seal certificate for each exposed fqdn for you,- if you have possibility to pre-generate wildcard certificate - why not? For domain resolving to localhost, like mentioned * - you need to take care of certificate on your own.

For generating letsencrypt certificates my current tool of choice - is - shell zero dependency tool. It supports number of dns providers, and generating wildcard certifate might be as simple as running short shell command.

Note that tool also takes care on prolonging certificate when necessary. Installing certificates into necessary folder also is as simple as executing shell script

In worse case scenario (if you haven't instructed with a command what to do on certificate prolongation) - you would need tp tale care on copying new set of certs once in 93 days.

e) Some tool you can inspect what happens with docker. There are many good console tools, but if you like one with web ui - portainer is definitely one of the best.

Now, when we have discussed components, let's combine them together:

Local setup - instance wide traefik setup for local development


We need:

traefik_certs folder, where we would store pre-generated wildcard certificate (you might have more than one) also here traefik will store information about own certificates.

traefik_conf folder, where we would store parts of the traefik configuration we want to exclude from docker-compose.

By default, certificates.toml tells traefik that we have one pregenerated certificate, which can be found under specified path in certs folder.

Controlling Makefile which helps you to create shared public network for docker to be used by traefik to look for exposed services, and up/down routines

and heart of the construction: main traefik docker-compose file, in order to make story shorter I will comment most important parts of the configuration

On a that moment, if you start the setup, i.e. docker-compose up -d, you already will get:

a) traefikUI at - not to much to change, but a nice bird eye view on currently detected services. Note, that page is served on a nice grean seal certificate you configured.


b) PortainerUI at alt which provides detailed insides in docker running on your machine, containers, services and et cetera.

Note that traefik docker-compose is fully independent component of your system without direct relation to any project you are currently worked on. This means that it can be constantly running on your host, like any other webserver.

At a moment when you need to expose some docker project you are currently working on to a traefik, you would need

a) add service exposed outside to the traefik-public network.

b) specify discovery rules, like fqdn for the service - "Host("

c) provide hints to traefik for any additional configuration, like redirections, authorization/password protection etc.

Once you launch such docker-compose in your project folder, it will immediately get exposed with traefik. Moreover - all your teammates working on project have exactly same experience, but on their own notebooks.

Your service(s) get exposed on a dedicated names, serving on a green seal certificates - almost identical copy of your production environment.


Installing setup on a public server

Instance wide traefik setup for remote development (branch deploys, etc) is done in a similar way, but you would need to protect better your intellectual property (saying you do not want anyone on a web to preview your branch deployes) as well as protect portainer and traefik dashboards with credentials or even fully remove them from public access.


Traefik has multiple middlewares to choose from

Most reasonable middlewares to consider would be





also for a public server traefik will take care on a generating grean seal certificates for you, if you haven't provided pregenerated wildcard certificate.

Also changes to the local_server setup would be activating letsencrypt certificates provider We introduce new mapped letsencrypt folder to store automatically retrieved certificates.

and we additionally activate letsencrypt acme provider in traefik

Althouth I recommend at least for host serving as branch deploys preview, pregenerate wild card certificate. It is quite useless to generate new certificate per very new branch deployed (

For services exposed through traefik, requiring automatic certificate from letsencrypt, you would need instruct traefik to use letsencrypt.

Full example for service exposed:


With described approach you are able to provide unobtrusive local development with traefik2, docker and letsencrypt individually as well as for all your teammates. Startup owners are able to enforce "branded" development environment, like app.lvh.mystartup.domain

Solution is universal, and works nicely with multiple projects, including standalone tools distributed as docker container.

You can easily able to extend approach to public server, implementing "preview server" for the same components. Traefik and docker allow you possibility also to introduce pull request previews in a reasonable time (in a day)

Mentioned in article examples can be tried at

local_server is the example of the development environment on your localhost, i.e.

public_server is the example of the environment environment that can be deployed to the public server.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment