Development Environment w/ Docker and Traefik 🤓💻️
Tags: traefik, docker, devjournal, productivity
Published: 2021-01-10 15:25:44

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][laradock].

## TLDR

1. Clone my [repository][docker-containers].
2. Follow the README.md.
3. Develop.
4. Deploy.

## Docker Containers for Local Development

{% github stctheproducer/docker-containers %}

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.

```bash
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.

```bash
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.

```bash
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][dnsmasq-blog].

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

{% gist https://gist.github.com/stctheproducer/3dd47aae53dd86081f946696c886fa39 file=dnsmasq.conf %}

After completing the configurations, I run the following commands:

```bash
  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:

{% gist https://gist.github.com/stctheproducer/3dd47aae53dd86081f946696c886fa39 file=resolvconf.conf %}

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

```bash
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-github].

{% github FiloSottile/mkcert %}

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][generate-sh]. 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][mkcert-github] documentation will solidify your knowledge of the tool. I will, however, show you how I used it below.

```bash
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.

```bash
./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][mkcert-mobile]. 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][mkcert-node], 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:

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

Now, onto the best part, the [proxy server](#traefik)! 🤩

## 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](#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.

```bash
cp .env.example .env

cp traefik.development.yaml traefik.yaml
```

Traefik has great [documentation on their website][traefik-docs] 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:

```bash
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:*

```bash
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:

```bash
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:

```bash
docker-compose stop serviceName
```

To destroy container services:

```bash
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.

[laradock]: https://laradock.io/ "Laradock"
[docker-containers]: https://github.com/stctheproducer/docker-containers "Docker containers"
[dnsmasq-blog]: https://www.linux.com/training-tutorials/dnsmasq-easy-lan-name-services/ "How to set up dnsmasq"
[mkcert-github]: https://github.com/FiloSottile/mkcert "The mkcert tool"
[generate-sh]: https://github.com/stctheproducer/docker-containers/blob/master/traefik/certs/generate.sh "Generate domain certificates"
[mkcert-mobile]: https://github.com/FiloSottile/mkcert#mobile-devices "Using mkcert in mobile development"
[mkcert-node]: https://github.com/FiloSottile/mkcert#using-the-root-with-nodejs "Using mkcert with NodeJS"
[traefik-docs]: https://docs.traefik.io "Traefik documentation"