I am a huge fan of Docker and I recently finished setting up my own environment for local development that I can easily port for production. I have to mention that it was heavily inspired by Laradock.

TLDR

1. Clone my repository.
2. Follow the README.md.
3. Develop.
4. Deploy.

Docker Containers for Local Development

Here's the stack I use (I may be biased towards Linux as I use Manjaro as my daily driver):

1. Docker: docker and docker-compose (I mean, docker containers, right? 🤷‍♂️)
2. A local DNS server such as dnsmasq (Optional)
3. An SSL certificate generator such as mkcert (Optional)
4. Traefik as a proxy server

Configuration

Environment Variables

I use environment variables to keep configuration out of the code so the .env.example file contains default values which I start with and create a .env file from.

cp .env.example .env

Docker Compose File

The docker-compose.example.yml contains defaults that will be in the docker-compose.yml file. This file works hand in hand with the .env file.

cp docker-compose.example.yml docker-compose.yml

Networks External to Docker Compose Project

The docker-compose.yml configuration makes use of two networks external to the docker-compose project, namely, dockernet and backdocker. I create the two networks using any IP range I want, keeping in mind that I'll have to update IP addresses in the docker-compose.yml configuration.

docker network create --subnet 192.168.90.0/24 --gateway 192.168.90.1 backdocker

docker network create --subnet 192.168.0.0/24 --gateway 192.168.0.1 dockernet

dnsmasq

dnsmasq makes it easier to have services and projects running under an optional domain name on my local machine. It's pretty much like having an automated /etc/hosts file. Once I have a domain set up, I don't need to worry about adding subdomains. A set up guide is available here.

The domain I use for my local development is usually local.test as can be seen in my dnsmasq.conf.

After completing the configurations, I run the following commands:

  dnsmasq --test # to confirm the syntax of the config file

  sudo systemctl enable dnsmasq # to enable the dnsmasq service

  sudo systemctl start dnsmasq # to start the dnsmasq service (or restart if it was running before)

I had to make changes to my resolvconf.conf so that I could browse external websites. Below is the final result of the changes:

After making said changes I run the following command and restarted the dnsmasq service:

sudo resolvconf -u # updates resolv subdirectories

And that's it, as long as I have a service running at port 80, the domain local.test will resolve to it without needing to touch my hosts file. To see how I handled services running at other ports, keep reading! 😉

mkcert

mkcert is an awesome tool I use for local SSL development. According to the developers of the tool:

mkcert is a simple tool for making locally-trusted development certificates. It requires no configuration.

Installation, and instructions on setting up can be found at this GitHub repository.

$ mkcert -install
Created a new local CA 💥
The local CA is now installed in the system trust store! ⚡️
The local CA is now installed in the Firefox trust store (requires browser restart)! 🦊

$ mkcert example.com "*.example.com" example.test localhost 127.0.0.1 ::1

Created a new certificate valid for the following names 📜
 - "example.com"
 - "*.example.com"
 - "example.test"
 - "localhost"
 - "127.0.0.1"
 - "::1"

The certificate is at "./example.com+5.pem" and the key at "./example.com+5-key.pem" ✅

I created a bash script to help with using mkcert once I installed it for the sole purpose of creating SSL certificates. It's available in my repository. The script itself is heavily commented and can be used to install and create a domain certificate all at once.

You could explore the script althouth the mkcert repository documentation will solidify your knowledge of the tool. I will, however, show you how I used it below.

mkcert -install # to create a new local CA

To create certificates that I used with my Traefik container, I run the following command from the root of my repository.

./traefik/certs/generate.sh "*.local.test"

The reason I used a wildcard domain is because of how I use service names as subdomains. Using a wildcard certificate will allow the creation of one certificate for a number of subdomains.

Usage in Mobile Development

When creating websites that should be mobile-first, I like to have the experience of entering qualified domain names. But for me to implement SSL, and to have the certificates trusted on my mobile device(s), I had to have the root CA installed on my device(s) as well. It is the rootCA.pem file in the folder printer by the command mkcert -CAROOT. The developers of mkcert explained it rather well in their documentation. In a nutshell:

On iOS, you can either use AirDrop, email the CA to yourself, or serve it from an HTTP server. After installing it, you must enable full trust in it.
For Android, you will have to install the CA and then enable user roots in the development build of your app.

Usage with Node.js

As explained by mkcert developers, I had to set the NODE_EXTRA_CA_CERTS environment variable. I had the following command appended to my ~/.bash_aliases file so that it run in every terminal:

export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"

Now, onto the best part, the proxy server! 🤩

Traefik

I use Traefik in development and production, as well. I find it easier to transition projects that way since the only difference between environments is just a configuration file. Additionally, I only ever have to expose port 80 or port 443 to the internet for any of the services I have, whether in production, or development.

Setting Up Traefik

1. Within the traefik directory, there is a .env.example file that I copied to a .env file similar to the overall configuration step. The only difference was that this .env was private to the Traefik container.
2. Depending on the environment, either the traefik.development.yaml or the traefik.production.yaml file were needed to be copied to a traefik.yaml file. Of course, since I was dealing with local development, I had to go with the former. It contained the configurations for the Traefik container.

cp .env.example .env

cp traefik.development.yaml traefik.yaml

Traefik has great documentation on their website that goes in-depth into my configurations.

Using Traefik to Proxy to Services

There were a few things I had to do first. Going forward every command was run within the traefik directory.

1. Create the dynamic directory where all the routes are stored and configured for Traefik to 'see'.
2. In order to use SSL with Traefik, it needs to know where the SSL certificates are. Since I generated it with the generate.sh script they were already in the right directory. I then copied the tls-certificates.yml file from the example-dynamic directory to the dynamic directory.
3. I had to copy the traefik-service.yml file from the example-dynamic/services directory into the dynamic directory so that I could interact with the Traefik dashboard at the URL specified in the traefik-service.yml file.

Working with Services

For docker projects, I used example-dynamic/services/container-service.yml as a template.

For locally running services, such as the ones using a process manager such as [PM2][pm2-manager], I used example-dynamic/services/http-service.yml as a template.

Working with Middleware

For middleware, I only made use of two, basic auth and https-redirection. To enable middleware, they had to be in the dynamic directory.

Then, in the middlewares array in a service router configuration, I listed the particular middleware with its middleware name, appending @file to it as the middleware configuration is contained in a file e.g. redirecthttp@file.

The basic auth middleware needed an array of users in the user:password format that had to be created using the htpasswd command. Any dollar signs in the resulting hash had to be doubled for escaping. That can be done with the following command:

echo $(htpasswd -nb $USERNAME $PASSWORD) | sed -e s/\\$/\\$\\$/g

# user:$$apr1$$XreceAun$$aWg8Y/AUo0CJDeFixyRuT0

Edit 10/01/2021: There's no need to escape the dollar signs. The pipe can be ignored so the final command is as below:

echo $(htpasswd -nb $USERNAME $PASSWORD)

# user:$apr1$XreceAun$aWg8Y/AUo0CJDeFixyRuT0

Managing Services

To manage the services, the following commands had to be run in the same directory as the docker-compose.yml file.

To run a service:

docker-compose up -d serviceName

where the serviceName is the name of a service in the docker-compose.yml file under the services object.

To stop a container service:

docker-compose stop serviceName

To destroy container services:

docker-compose down

Final Remarks

This setup helps me develop in an environment that differs ever so slightly from a production environment in an effort to keep deploying to production as effortless as possible.