docs: adding more friendly quick-start guide

Author: lotyp

.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,23 +77,59 @@ If you **like/use** this project, please consider ⭐️ **starring** it. Thanks
 
 <br>
 
-## ⚙️ Configuration
+## 🚀 Quick Start (macOS)
 
-### → Cloning and setting up envs
+1. Install Homebrew (**optional** if not installed):
 
-1. Clone repository:
+   ```bash
+   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+   ```
+
+2. **Install `mkcert` and `nss`:**
+
+   `mkcert` is a tool that creates locally-trusted development certificates, `nss` provides support of mkcert certificates in macOS.
 
    ```bash
-   git clone git@github.com:wayofdev/docker-shared-services.git
+   brew install mkcert nss
    ```
 
-2. Generate default .env file:
+3. **Create shared projects Directory:**
+
+   This repository should be run once per machine, so let's create a shared directory for this project:
+
+   ```bash
+   mkdir -p ~/projects/infra && cd ~/projects/infra
+   ```
+
+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
+   ```
+
+5. **Create `.env` file:**
+
+   Generate a default `.env` file, which contains configuration settings for the project.
 
    ```bash
    make env
    ```
 
-   Edit the created `.env` file if necessary. You may want to change the default domain.
+   Open this file and read the notes inside to make any necessary changes to fit your setup.
+
+6. **Install root certificate** and generate default project 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
+   ```
+
+   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).
 
 <br>