Project: Unified Aether Platform Orchestration (V3)

Status: ✅ COMPLETE (2026-03-10) ae_app is live in aether_container_env/docker-compose.yml. Both frontend and backend deploy together via npm run deploy:staging / npm run deploy:prod. Internal ae_api networking active. Healthcheck wired. Old ae_env_node_app is superseded (archive when ready).

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:

# --- 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:

    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:

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

Healthcheck: Ensure src/routes/health/+server.ts is active.
Internal Proxy Test: Update SvelteKit's PUBLIC_AE_API_SERVER to ae_api (internal) and verify connectivity.
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)

# From aether_container_env/
docker compose up -d --build --remove-orphans
docker compose ps
docker compose logs -f ae_app

4.1 KiB Raw Blame History