Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: adding more friendly quick-start guide #134

Merged
merged 2 commits into from
Jun 3, 2024
Merged

docs: adding more friendly quick-start guide #134

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
12c6fb7
docs: adding more friendly quick-start guide
lotyp Jun 3, 2024
d86b21a
docs: updating readme
lotyp Jun 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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=
Expand Down
149 changes: 82 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down