From 7139753c7938bc942ac2ede5b020941bcbacde5d Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Tue, 10 Mar 2026 14:24:09 -0400 Subject: [PATCH] Docs: update TODO and add combined Docker architecture reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit TODO__Agents.md: Mark QR code on badge front as done — ae_comp__badge_obj_view.svelte already generates the QR via core_func.js_generate_qr_code() and renders it inside a {#await qr_data_url} block on the badge face. PROJECT__AE_combined_front_back_Docker.md: New reference document covering the combined front+back Docker orchestration architecture (consolidated notes from the session). --- .../PROJECT__AE_combined_front_back_Docker.md | 103 ++++++++++++++++++ documentation/TODO__Agents.md | 4 +- 2 files changed, 104 insertions(+), 3 deletions(-) create mode 100644 documentation/PROJECT__AE_combined_front_back_Docker.md diff --git a/documentation/PROJECT__AE_combined_front_back_Docker.md b/documentation/PROJECT__AE_combined_front_back_Docker.md new file mode 100644 index 00000000..9a75c35b --- /dev/null +++ b/documentation/PROJECT__AE_combined_front_back_Docker.md @@ -0,0 +1,103 @@ +# Project: Unified Aether Platform Orchestration (V3) +> **Goal:** Consolidate the SvelteKit Frontend and FastAPI Backend into a single Docker Compose environment within `aether_container_env`. + +## 1. Overview & Benefits +Currently, the platform runs in two separate Docker environments (`ae_env_node_app` and `aether_container_env`). Combining them into one allows for: +- **Unified Lifecycle:** Start/Stop/Update the entire stack with one command. +- **Internal Networking:** The Frontend (SvelteKit) can communicate with the Backend (FastAPI) via the high-speed internal Docker network (`ae_api:5005`) instead of routing through external IPs. +- **Shared Infrastructure:** Single instances of Redis, Dozzle, and Nginx serving both tiers. +- **Simplified Deployment:** Reduces the need for sibling directory dependencies on production servers. + +--- + +## 2. Target Architecture (Workstation & Prod) +The unified environment will reside in `~/OSIT_dev/aether_container_env/`. + +### Directory Mapping +- **API Source:** `~/OSIT_dev/aether_api_fastapi` -> Mounted to `ae_api` +- **App Source:** `~/OSIT_dev/aether_app_sveltekit` -> Mounted to `ae_app` +- **Nginx Config:** `~/OSIT_dev/aether_container_env/conf/nginx/` +- **Logs:** `~/OSIT_dev/aether_container_env/logs/` + +--- + +## 3. Implementation Plan + +### Step 1: Update `aether_container_env/.env` +Add these new variables to the master `.env` file: +```bash +# --- SvelteKit Frontend settings --- +AE_APP_SRC=/home/scott/OSIT_dev/aether_app_sveltekit +CONTAINER_AE_APP=ae_app_dev +AE_APP_REPLICAS=4 +AE_APP_NODE_PORT=3001 +# Note: Use internal DNS 'ae_api' for PUBLIC_AE_API_SERVER_INTERNAL +``` + +### Step 2: Integrate `ae_app` into `docker-compose.yml` +Add the consolidated SvelteKit service. This replaces the legacy Flask service: +```yaml + ae_app: + restart: always + build: + context: ${AE_APP_SRC} + dockerfile: Dockerfile + target: deploy-node + scale: ${AE_APP_REPLICAS} + env_file: + - ./.env + ports: + - "${AE_APP_NODE_PORT}:3000" + extra_hosts: + - "${DOCKER_AE_SERVER_EXTRA_HOST}" + - "${DOCKER_AE_APP_SERVER_EXTRA_HOST}" + - "${DOCKER_AE_API_SERVER_EXTRA_HOST}" + volumes: + # Mount source for real-time dev (Optional for production) + - ${AE_APP_SRC}:/srv/aether_app + - ${HOSTED_FILES_SRC}:/srv/hosted_files + - ${HOSTED_TMP_SRC}:/srv/hosted_tmp + depends_on: + - ae_api + - redis + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" +``` + +### Step 3: Nginx Gateway Configuration +Update (or create) the Nginx template in `conf/nginx/` to route traffic to the internal `ae_app` service. + +**Example Upstream Block:** +```nginx +upstream svelte_backend { + # Internal Docker DNS handles load balancing across replicas + server ae_app:3000; + # ip_hash; # Enable if session persistence is needed +} +``` + +### Step 4: Verification & Migration +1. **Healthcheck:** Ensure `src/routes/health/+server.ts` is active. +2. **Internal Proxy Test:** Update SvelteKit's `PUBLIC_AE_API_SERVER` to `ae_api` (internal) and verify connectivity. +3. **Clean Up:** Once verified, the old `ae_env_node_app` directory can be archived. + +--- + +## 4. Scaling & Performance +- **API Scaling:** Controlled by `AE_API_REPLICAS`. +- **App Scaling:** Controlled by `AE_APP_REPLICAS`. +- **Memory Management:** Each replica is isolated. Shared state (caching) is handled via the internal **Redis** service. +- **Healthchecks:** Docker will automatically restart any `ae_app` replica that fails the `/health` check. + +--- + +## 5. Deployment Commands (Unified) +```bash +# From aether_container_env/ +docker compose up -d --build --remove-orphans +docker compose ps +docker compose logs -f ae_app +``` diff --git a/documentation/TODO__Agents.md b/documentation/TODO__Agents.md index 42b45613..23230458 100644 --- a/documentation/TODO__Agents.md +++ b/documentation/TODO__Agents.md @@ -22,9 +22,7 @@ - ~~**Dark mode select option hover (Manage Files):**~~ ✅ Fixed (2026-03-10) — Added `html.dark { color-scheme: dark }` / `html.light { color-scheme: light }` to `app.css`. This globally syncs all native browser controls (select dropdowns, scrollbars, inputs) to the app's class-based dark mode, rather than a per-element fix. ### [Badges] Remaining badge work before first live event -- **QR code on badge front:** `ae_comp__badge_obj_view.svelte` — display QR on the printed - face when template has `show_qr` (or equivalent) toggled on. Use same QR generation as - review form (`core_func.js_generate_qr_code`). See TASK 4 in `PROJECT__AE_Events_Badges_Review_Print.md`. +- ~~**QR code on badge front:**~~ ✅ Done — `ae_comp__badge_obj_view.svelte` already generates the QR via `core_func.js_generate_qr_code()` and renders it on the badge face inside a `{#await qr_data_url}` block. `hide_qr` provides a double-click print-suppress toggle. Consent text controlled by `allow_tracking`. The template `show_qr` gate was never needed — the QR section is always present. - **Badge print controls UX polish:** Scott has improvements in mind — TBD next session. File: `ae_comp__badge_print_controls.svelte`.