docs: update README and CHEATSHEET to reflect final correct architecture
- Traffic diagram corrected: both app and api route through ae_web_dev - Removed outdated 'two options' scaling section for ae_app - Added port reference table to CHEATSHEET - Scaling section simplified: change replicas, done, home nginx never changes - localhost link corrected from 3001 to 8888 (LAN HTTP via ae_web_dev)
This commit is contained in:
Scott Idem
@@ -1,54 +1,41 @@
|
||||
# Aether Docker Cheat Sheet 🚀
|
||||
|
||||
## 🚀 Deployment & Updates
|
||||
- **Full Rebuild (Fast):** `docker compose up -d --build`
|
||||
- **Rebuild SvelteKit UI:** `docker compose up -d --build ae_app`
|
||||
- **Restart API (Pick up Python changes):** `docker compose restart ae_api`
|
||||
- **Switch Build Mode:** Edit `.env` -> `AE_APP_BUILD_MODE=prod` -> `docker compose up -d --build ae_app`
|
||||
- **Full Rebuild:** `docker compose up -d --build`
|
||||
- **Rebuild SvelteKit only:** `docker compose up -d --build ae_app`
|
||||
- **Restart API (pick up Python changes):** `docker compose restart ae_api`
|
||||
- **Switch Build Mode:** Edit `.env` → `AE_APP_BUILD_MODE=prod` → `docker compose up -d --build ae_app`
|
||||
- **Shut everything down:** `npm run compose:down` (from `aether_app_sveltekit/`)
|
||||
|
||||
## 🛠️ Management Links
|
||||
- **SvelteKit Frontend:** [http://localhost:3001](http://localhost:3001)
|
||||
- **FastAPI Documentation:** [https://dev-api.oneskyit.com/docs](https://dev-api.oneskyit.com/docs)
|
||||
- **Database (phpMyAdmin):** [http://localhost:8081](http://localhost:8081)
|
||||
- **SvelteKit Frontend:** [http://localhost:8888](http://localhost:8888) (LAN HTTP via ae_web_dev)
|
||||
- **FastAPI Docs:** [https://dev-api.oneskyit.com/docs](https://dev-api.oneskyit.com/docs)
|
||||
- **Database (phpMyAdmin):** [http://localhost:8081](http://localhost:8081) (requires `--profile database`)
|
||||
- **Logs (Dozzle):** [http://localhost:8881](http://localhost:8881)
|
||||
|
||||
## 💾 Database Operations
|
||||
- **Manual Backup:** `./backup_db.sh` (Hot backup, live container)
|
||||
- **Manual Restore:** `./restore_db.sh [path_to_file.gz]` (Automated password/grant reset)
|
||||
- **Conference Export:** `./export_db.sh` (Saves to `backups/conference_export/`)
|
||||
- **Automated Import:** Drop file in `backups/import/` -> Run `./check_and_import.sh`.
|
||||
## 🔌 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) |
|
||||
|
||||
## 📈 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.
|
||||
|
||||
### ae_api — scales via Docker DNS (no host ports needed)
|
||||
`ae_api` has no host ports. External traffic enters via `ae_web_dev` (port 5060/443),
|
||||
which round-robins across all `ae_api` replicas using Docker's internal DNS.
|
||||
- Edit `.env` → `AE_APP_REPLICAS=X` or `AE_API_REPLICAS=X`
|
||||
- Run `docker compose up -d` (or `up -d ae_app` for app-only)
|
||||
|
||||
1. Edit `.env` → `AE_API_REPLICAS=X`
|
||||
2. Run `docker compose up -d`
|
||||
|
||||
No home-server nginx changes needed.
|
||||
|
||||
### ae_app — two scaling options
|
||||
|
||||
**Option A (recommended): Route through ae_web_dev (same as ae_api)**
|
||||
- Home server nginx points `dev-*.oneskyit.com` at `workstation:443`
|
||||
- ae_web_dev round-robins to `ae_app` replicas via Docker DNS
|
||||
- No host ports needed on ae_app, no home nginx changes when scaling
|
||||
- Same topology as ae_api
|
||||
|
||||
**Option B (current): Direct host port binding**
|
||||
- Home server nginx points at `workstation:3001`, `3002`, etc.
|
||||
- `AE_APP_NODE_PORT_RANGE=3001-3006` in `.env`; Docker assigns one port per replica
|
||||
- Must uncomment matching entries in home server nginx upstream when adding replicas
|
||||
- Maximum 6 replicas without changing the range
|
||||
|
||||
To scale with Option B:
|
||||
1. Edit `.env` → `AE_APP_REPLICAS=X` (max 6 with current range)
|
||||
2. Run `docker compose up -d ae_app`
|
||||
3. Uncomment matching port entries in home server nginx upstream
|
||||
4. Reload home server nginx
|
||||
## 💾 Database Operations
|
||||
- **Manual Backup:** `./backup_db.sh` (hot backup, live container)
|
||||
- **Manual Restore:** `./restore_db.sh [path_to_file.gz]`
|
||||
- **Conference Export:** `./export_db.sh` (saves to `backups/conference_export/`)
|
||||
- **Automated Import:** Drop file in `backups/import/` → run `./check_and_import.sh`
|
||||
|
||||
## 🧹 Maintenance
|
||||
- **Internal Logs:** Docker handles rotation automatically (10MB limit).
|
||||
- **External Proxy:** Point your home server to `[Workstation_IP]:5060`.
|
||||
- **Dozzle:** Live log viewer at port 8881 — no auth currently (LAN only).
|
||||
|
||||
26
README.md
26
README.md
@@ -9,24 +9,30 @@ Understanding this prevents configuration mistakes.
|
||||
```
|
||||
External Internet
|
||||
↓
|
||||
Home Server Nginx (reverse proxy)
|
||||
Home Server Nginx (SSL termination, domain routing)
|
||||
↓ ↓
|
||||
workstation:443 workstation:5060
|
||||
(ae_web_dev HTTPS) (ae_web_dev API gateway)
|
||||
workstation:3001 workstation:5060
|
||||
(AE_APP_GATEWAY_PORT) (AE_API_GATEWAY_PORT)
|
||||
↓ ↓
|
||||
ae_web_dev (Docker nginx, port 80)
|
||||
↓ ↓
|
||||
svelte_backend fastapi_backend
|
||||
(Docker DNS) (Docker DNS)
|
||||
(Docker DNS round-robin) (Docker DNS round-robin)
|
||||
↓ ↓
|
||||
ae_app replicas ae_api replicas
|
||||
(round-robin) (round-robin)
|
||||
```
|
||||
|
||||
**Both ae_app and ae_api can scale via Docker DNS round-robin** when home server
|
||||
nginx routes through `ae_web_dev`. This is the recommended topology.
|
||||
**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.
|
||||
|
||||
Alternatively, ae_app can be reached directly via host port range (`3001-3006`),
|
||||
but this requires manually updating the home server nginx upstream for each replica.
|
||||
See the Scaling section in CHEATSHEET.md.
|
||||
**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
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user