From 1aa4186f4a11511c9a431ecac9a363b246143546 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Tue, 10 Mar 2026 18:24:31 -0400 Subject: [PATCH] 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) --- CHEATSHEET.md | 67 +++++++++++++++++++++------------------------------ README.md | 26 ++++++++++++-------- 2 files changed, 43 insertions(+), 50 deletions(-) diff --git a/CHEATSHEET.md b/CHEATSHEET.md index 3f5345f..5ec6485 100644 --- a/CHEATSHEET.md +++ b/CHEATSHEET.md @@ -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). diff --git a/README.md b/README.md index 91ee6e8..4b6a9ca 100644 --- a/README.md +++ b/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 ---