docs: updated README and CHEATSHEET with multi-stack and shared network architecture.

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)

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
 ```