From f636c021bc86246b923660f3eda5df98070847cc Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Thu, 12 Mar 2026 02:28:43 -0400 Subject: [PATCH] docs: updated README and CHEATSHEET with multi-stack and shared network architecture. --- CHEATSHEET.md | 27 +++++++++++++-------------- README.md | 31 +++++++++++++++---------------- 2 files changed, 28 insertions(+), 30 deletions(-) diff --git a/CHEATSHEET.md b/CHEATSHEET.md index 5ec6485..815acb3 100644 --- a/CHEATSHEET.md +++ b/CHEATSHEET.md @@ -13,22 +13,21 @@ - **Database (phpMyAdmin):** [http://localhost:8081](http://localhost:8081) (requires `--profile database`) - **Logs (Dozzle):** [http://localhost:8881](http://localhost:8881) -## 🔌 Port Reference -| Port | Variable | Purpose | -|------|-----------------------|--------------------------------------------------| -| 3001 | `AE_APP_GATEWAY_PORT` | App gateway — home nginx → ae_app replicas | -| 5060 | `AE_API_GATEWAY_PORT` | API gateway — home nginx → ae_api replicas | -| 8888 | `OSIT_WEB_HTTP_PORT` | LAN HTTP direct access (no home server needed) | -| 8081 | `AE_PMA_PORT` | phpMyAdmin (database profile only) | -| 8881 | — | Dozzle log viewer | -| 3306 | `AE_DB_EXTERNAL_PORT` | MariaDB direct (database profile only) | +## 🔌 Multi-Stack Port Reference +To run multiple stacks (`test`, `bak`, `prod`) on one host, you **must** assign unique host ports in each `.env`. -## 📈 Scaling -Both services scale via Docker DNS round-robin inside `ae_web_dev`. -Home server nginx **never needs to change** — it always points to the same port. +| Port Type | Variable | Example (Test) | Example (Bak) | Example (Prod) | +|-----------------|-----------------------|----------------|---------------|----------------| +| App Gateway | `AE_APP_GATEWAY_PORT` | 3009 | 3002 | 3001 | +| API Gateway | `AE_API_GATEWAY_PORT` | 5063 | 5062 | 5061 | +| LAN Direct HTTP | `OSIT_WEB_HTTP_PORT` | 32887 | 32891 | 32890 | +| Dozzle Logs | `AE_DOZZLE_PORT` | 8889 | 8882 | 8881 | +| MariaDB Direct | `AE_DB_EXTERNAL_PORT` | 32769 | 32770 | 32768 | -- Edit `.env` → `AE_APP_REPLICAS=X` or `AE_API_REPLICAS=X` -- Run `docker compose up -d` (or `up -d ae_app` for app-only) +## 🏗️ Multi-Stack Isolation +1. **Network Name:** Set `AE_NETWORK_NAME=ae_test_net` (etc) to prevent Docker network name collisions. +2. **Container Names:** Set `CONTAINER_` variables (e.g., `CONTAINER_WEB=ae_web_test`) to prevent Docker from refusing to start "conflicting" containers. +3. **Internal Shared Net:** All stacks must connect to `aether_shared_net` to reach a shared MariaDB/Redis. ## 💾 Database Operations - **Manual Backup:** `./backup_db.sh` (hot backup, live container) diff --git a/README.md b/README.md index 7357f9f..05df033 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This repository provides the unified Docker orchestration and configuration for ## 🌐 Traffic Architecture -Understanding this prevents configuration mistakes. +The V3 environment uses a **Dual-Network** strategy to support multiple isolated stacks (`test`, `bak`, `prod`) on a single host while sharing core services like MariaDB or Redis. ``` External Internet @@ -22,23 +22,22 @@ workstation:3001 workstation:5060 ae_app replicas ae_api replicas ``` -**Key points:** -- Home server nginx terminates SSL and routes by domain name to one of two stable ports. It never needs to know about replicas. -- `ae_web_dev` is the internal load balancer. It routes by `server_name` to the correct upstream, and Docker DNS automatically round-robins across all replicas. -- SSL is terminated at the home server. Internal traffic (home server → workstation → containers) is plain HTTP — no internal certs needed. -- To scale, change `AE_APP_REPLICAS` or `AE_API_REPLICAS` in `.env` and run `docker compose up -d`. Home server nginx never changes. - -**Host ports exposed by ae_web_dev:** -- `:3001` — App gateway (SvelteKit) -- `:5060` — API gateway (FastAPI) -- `:8888` — LAN HTTP (direct local access without going through home server) -- `:443` — commented out; SSL terminates at home server, not internally +**Key Improvements:** +- **Scalable Routing:** Nginx uses Regex (`~^(dev|test|bak|sr|prod)?-?...`) to automatically handle any environment prefix without configuration changes. +- **Isolated Stacks:** Each deployment uses a unique `AE_NETWORK_NAME` and `CONTAINER_` prefix to prevent collisions. +- **Shared Services:** Core infrastructure (DB/Redis) resides on the `aether_shared_net` which must be created manually once. --- ## 🚀 Quick Start -### 1. Initialize Directory Structure +### 1. Initialize Host Network +Before starting your first stack, create the shared internal network: +```bash +docker network create aether_shared_net +``` + +### 2. Initialize Directory Structure Create the base directory and clone this environment: ```bash sudo mkdir -p /srv/env/aether @@ -46,12 +45,12 @@ sudo chown -R $USER:$USER /srv/env/aether git clone https://bitbucket.org/oneskyit/one-sky-it-container-environment.git /srv/env/aether/container_env ``` -### 2. Configure Environment Settings -Copy the template and update it with your local paths and credentials: +### 3. Configure Environment Settings +Copy the template and update it with your unique stack identifiers: ```bash cd /srv/env/aether/container_env cp env.default .env -# Edit .env to match your host system (Paths, DB, Ports) +# CRITICAL: Set unique CONTAINER_ prefixes and AE_NETWORK_NAME for each stack vim .env ```