Merge pull request #134 from wayofdev/ci/e2e-testing

.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=

README.md

@@ -77,119 +77,134 @@ If you **like/use** this project, please consider ⭐️ **starring** it. Thanks
 
 <br>
 
-## ⚙️ 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.
-
-<br>
-
-## 💻 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.            |
-
-<br>
-
-### → 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:**
 
-<br>
+   ```bash
+   git clone \
+     [email protected]: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
+   ```
 
-<br>
+   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
    ```
 
-<br>
-
-### → 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** — <https://ui.wod.docker> or <https://ui.docker>
+    Open [https://router.docker](https://router.docker)
 
-**Pg-admin** (if `docker-compose.override.yaml` was enabled) — <https://pg-admin.wod.docker> or <https://pg-admin.docker>
+At this point, you should have a working local development environment with DNS and SSL support for your projects.
 
 <br>
 
-## 🧪 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
 ```
 
 <br>