diff --git a/.env.example b/.env.example index 3caf26f6..7cc12b4b 100644 --- a/.env.example +++ b/.env.example @@ -1,18 +1,27 @@ +# # SS = Shared Services # https://docs.docker.com/compose/reference/envvars/#compose_project_name +# COMPOSE_PROJECT_NAME=ss +# # Domain, under which default, shared services will run. # Default: .wod # Example subdomains, under which services will run under: # - pg-admin.wod.docker # - router.wod.docker # - ui.wod.docker -# Can be left blank, but then $TLS_DOMAINS need to contain all top level domains +# Can be left blank, but then $TLS_DOMAINS need to contain all top level domains of your projects. +# # Example: +# Using empty SHARED_DOMAIN_SEGMENT="" # TLS_DOMAINS="pg-admin.docker router.docker ui.docker" +# Using custom SHARED_DOMAIN_SEGMENT=".wod" +# TLS_DOMAINS="pg-admin.wod.docker router.wod.docker ui.wod.docker" +# SHARED_DOMAIN_SEGMENT= +# # Specify domains for mkcert # Because of browser limitations, each top-level domain should be added separately. # This ensures that certificates are correctly recognized by browsers. @@ -47,6 +56,9 @@ TLS_DOMAINS="ui.docker router.docker pg-admin.docker *.wod.docker *.tpl.wod.dock # For more information, see: # https://github.com/DrPsychick/docker-dnsmasq # +# Note: To use, for example .mac domain, you need to change +# DMQ_GLOBAL=address=/docker/127.0.0.1 (to =>) DMQ_GLOBAL=address=/mac/127.0.0.1 +# DMQ_DHCP_DNS=dhcp-option=6,172.17.10.1,8.8.8.8,8.8.4.4 DMQ_DHCP_GATEWAY=dhcp-option=3,172.17.10.1 DMQ_DHCP_PXE= diff --git a/README.md b/README.md index 6b2231a4..1b30c6f0 100644 --- a/README.md +++ b/README.md @@ -77,119 +77,134 @@ If you **like/use** this project, please consider โญ๏ธ **starring** it. Thanks
-## โš™๏ธ Configuration +## ๐Ÿš€ Quick Start (macOS) -### โ†’ Cloning and setting up envs - -1. Clone repository: +1. Install Homebrew (**optional** if not installed): ```bash - git clone git@github.com:wayofdev/docker-shared-services.git + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` -2. Generate default .env file: +2. **Install `mkcert` and `nss`:** + + `mkcert` is a tool that creates locally-trusted development certificates, `nss` provides support of mkcert certificates in macOS. ```bash - make env + brew install mkcert nss ``` - Edit the created `.env` file if necessary. You may want to change the default domain. - -
- -## ๐Ÿ’ป Usage - -### โ†’ Running with a blank shared domain segment +3. **Create shared projects Directory:** -Leave the `SHARED_DOMAIN_SEGMENT` blank to run shared services under the first level domain. For example: + This repository should be run once per machine, so let's create a shared directory for this project: - | 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: + ```bash + mkdir -p ~/projects/infra && cd ~/projects/infra + ``` - | Address | - |-------------------------| - | router.**wod**.docker | - | pg-admin.**wod**.docker | - | ui.**wod**.docker | - | etc. | +4. **Clone this repository:** -
+ ```bash + git clone \ + git@github.com:wayofdev/docker-shared-services.git \ + ~/projects/infra/docker-shared-services && \ + cd ~/projects/infra/docker-shared-services + ``` -### โ†’ SSL certificates +5. **Create `.env` file:** -Don't forget to include first level domains into the `TLS_DOMAINS` variable. Default certificates will be created for these domains and wildcards: + Generate a default `.env` file, which contains configuration settings for the project. -| 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](https://github.com/wayofdev/laravel-starter-tpl) | + ```bash + make env + ``` -
+ Open this file and read the notes inside to make any necessary changes to fit your setup. -### โ†’ Finishing +6. **Install root certificate** and generate default project certs: -1. Install root certificate into system and generate default certs: + This step installs the root certificate into your system's trust store and generates default SSL certificates for your local domains, which are listed in the `.env` file, under variable `TLS_DOMAINS`. ```bash make cert-install ``` -2. (Optional) Enable docker-compose.override file to run extra services, like pg-admin and others: + Currently, on macOS you may need to enter password several times to allow mkcert to install root certificate. + This is a one-time operation and details can be found in this upstream [issue](https://github.com/FiloSottile/mkcert/issues/415). - ```bash - make override - ``` +7. **Run this project:** -3. Run this repository: + Start the Docker services defined in the repository. ```bash make up ``` -4. Check that everything works: +8. **Check that all Docker services are running:** ```bash make ps make logs ``` -
- -### โ†’ Outcome +9. **Ping `router.docker` to check if DNS is working:** -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. + Ensure that the DNS setup is functioning correctly. -**Traefik dashboard** โ€” [https://router.wod.docker](https://router.wod.docker/dashboard/#/) + ```bash + ping router.docker + ``` -![Traefik dashboard](.github/assets/traefik.png?raw=true "Traefik dashboard example") +10. **Access Traefik dashboard:** -**Portrainer** โ€” or + Open [https://router.docker](https://router.docker) -**Pg-admin** (if `docker-compose.override.yaml` was enabled) โ€” or +At this point, you should have a working local development environment with DNS and SSL support for your projects.
-## ๐Ÿงช 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`: +## โšก๏ธ Connecting your Projects to Shared Services + +To connect your projects to the shared services, configure your project's `docker-compose.yaml` file to connect to the shared network and Traefik. + +For a quick example, you can check this [Laravel Starter Template](https://github.com/wayofdev/laravel-starter-tpl) repository's [docker-compose.yaml](https://github.com/wayofdev/laravel-starter-tpl/blob/develop/docker-compose.yaml) file, which includes a sample configuration for a Laravel project. + +### โ†’ Sample Configuration + +Your project should use the shared Docker network `network.ss` and Traefik labels to expose services to the outside world. + +```diff +--- + +services: + web: + image: wayofdev/nginx:k8s-alpine-latest + container_name: ${COMPOSE_PROJECT_NAME}-web + restart: on-failure ++ networks: ++ - default ++ - shared + depends_on: + - app + links: + - app + volumes: + - ./app:/app:rw,cached + - ./.env:/app/.env ++ labels: ++ - traefik.enable=true ++ - traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.rule=Host(`api.${COMPOSE_PROJECT_NAME}.docker`) ++ - traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.entrypoints=websecure ++ - traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.tls=true ++ - traefik.http.services.api-${COMPOSE_PROJECT_NAME}-secure.loadbalancer.server.port=8880 ++ - traefik.docker.network=network.ss + +networks: ++ shared: ++ external: true ++ name: network.ss ++ default: ++ name: project.laravel-starter-tpl -```bash -make test ```