Docker Shared Services

The repository provides Docker-powered local development experience for WOD projects that is compatible with macOS and Linux.

Repository contains a set of docker-compose files and Træfik configuration with SSL support to allow running a local network with custom DNS, which enables support for developing microservices locally with access outside the Docker network.

→ Purpose

Developers will be familiar with the process of updating your /etc/hosts file to direct traffic for yourproject.docker or yourproject.domain.docker to 127.0.0.1. Most will also be familiar with the problems of this approach:

• it requires a configuration change every time you add or remove a project; and
• it requires administration access to make the change.

For Linux and macOS users there is a solution – dnsmasq, which replaces the need for you, to edit the hosts file for each project you work with. Dnsmasq works good together with Træfik and Docker.

This repository configures Traefik to run together with, installed in system, dnsmasq and serve you system wide DNS solution to work with your microservices and use DNS and SSL features with local domains.

🚩 Requirements

• macOS Monterey or Linux
• Docker 20.10 or newer
  • How To Install and Use Docker on Ubuntu 22.04
• Installed mkcert binary in system
  • See full installation instructions in their official README.md
  • Quick installation on macOS: brew install mkcert nss
• Installed and configured dnsmasq daemon
  • Can be installed and configured automatically via our own ansible-role-dnsmasq
  • DNSMasq service now is shipped and configured with this repository.

💻 Usage

→ Cloning and setting up envs

1. Clone repository:

   $ git clone git@github.com:wayofdev/docker-shared-services.git

2. Generate default .env file:

   $ make env

   Edit the created .env file if necessary. You may want to change the default domain.

→ Running with a blank shared domain segment:

Leave the SHARED_DOMAIN_SEGMENT blank to run shared services under the first level domain. For example:

Address
router.docker
pg-admin.docker
ui.docker
etc.

→ Running with a default or custom shared domain segment:

Set the segment to run shared services under a subdomain: SHARED_DOMAIN_SEGMENT=.wod. Services will run under that segment. For example:

Address
router.wod.docker
pg-admin.wod.docker
ui.wod.docker
etc.

→ SSL certificates:

Don't forget to include first level domains into the TLS_DOMAINS variable. Default certificates will be created for these domains and wildcards:

SSL certificate	Comments
ui.docker	Included as fallback, if SHARED_DOMAIN_SEGMENT was left blank.
router.docker	Included as fallback, if SHARED_DOMAIN_SEGMENT was left blank.
pg-admin.docker	Included as fallback, if SHARED_DOMAIN_SEGMENT was left blank.
*.wod.docker	All subdomains under this wildcard. Only one level of nesting will work in most of the browsers.
*.tpl.wod.docker	For default template, generated from laravel-starter-tpl

→ Finishing:

1. Install root certificate into system and generate default certs:

   $ make cert-install

2. (Optional) Enable docker-compose.override file to run extra services, like pg-admin and others:

   $ make override

3. Run this repository:

   $ make up

4. Check that everything works:

   $ make ps
   $ make logs

→ Outcome

Services will be running under shared docker network, called ss_shared_network and all microservices, that will share same network, will be visible for Traefik, and local DNS, served by dnsmasq, will be available.

Traefik dashboard — https://router.wod.docker

Portrainer — https://ui.wod.docker or https://ui.docker

Pg-admin (if docker-compose.override was enabled) — https://pg-admin.wod.docker or https://pg-admin.docker

🧪 Testing

You can check Makefile to get full list of commands for local testing. For testing, you can use these commands to test whole role or separate tasks:

Testing docker-compose using dcgoss:

$ make test

🤝 License

🙆🏼‍♂️ Author Information

This repository was created in 2022 by lotyp / wayofdev.

🫡 Supporters