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 http://lvh.me is a free service that resolves itself along with all subdomains to localhost, and similar to it service nip.io which allows to code ip address to resolve into domain name 192-168-1-250.nip.io, 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)
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: *.lvh.voronenko.net - resolving to localhost, or *.preview.project.net - 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 *.lvh.voronenko.net - you need to take care of certificate on your own.
For generating letsencrypt certificates my current tool of choice - is acme.sh - shell zero dependency tool. It supports number of dns providers, and generating wildcard certifate might be as simple as running short shell command.
https://gist.github.com/fecac43fbe799da978228f8e7b2f4fd2
Note that tool also takes care on prolonging certificate when necessary. Installing certificates into necessary folder also is as simple as executing shell script
https://gist.github.com/c760125df9fabb847c5b12c8540a770f
In worse case scenario (if you haven't instructed acme.sh 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:
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.
https://gist.github.com/164f85330e9b2cb371ffa00d5e836050
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
https://gist.github.com/e5b0f3e15d1c53b29e789e73e05f7f04
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
https://gist.github.com/88eb172fd1f420da0422b189ac9b4567
On a that moment, if you start the setup, i.e. docker-compose up -d, you already will get:
a) traefikUI at https://traefik.lvh.voronenko.net/ - 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 https://docker.lvh.voronenko.net/
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(whoami.lvh.voronenko.net)"
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.
https://gist.github.com/c2e20144490a1d8874ecb1a9d6849aa5
Your service(s) get exposed on a dedicated names, serving on a green seal certificates - almost identical copy of your production environment.
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 https://docs.traefik.io/middlewares/overview/
Most reasonable middlewares to consider would be
BasicAuth https://docs.traefik.io/middlewares/basicauth/
DigestAuth https://docs.traefik.io/middlewares/digestauth/
IPWhiteList https://docs.traefik.io/middlewares/ipwhitelist/
RateLimit https://docs.traefik.io/middlewares/ratelimit/
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.
https://gist.github.com/4a30f5c0e8141c06cfd044eaa9b98f61
and we additionally activate letsencrypt acme provider in traefik
https://gist.github.com/b7171787252f39f6c33f0e63f100e47f
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 (branchname.preview.voronenko.net)
For services exposed through traefik, requiring automatic certificate from letsencrypt, you would need instruct traefik to use letsencrypt.
https://gist.github.com/e731878a962a6d05c1ed34556f381c52
Full example for service exposed:
https://gist.github.com/66cfc38e350f3221ab8e273e4611ee6b
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 https://github.com/Voronenko/traefik2-compose-template
local_server is the example of the development environment on your localhost, i.e. https://someapp.lvh.voronenko.net/
public_server is the example of the environment environment that can be deployed to the public server.