# Aether Framework - Docker Environment (Unified V3)

This repository provides the unified Docker orchestration and configuration for the Aether Platform. It manages the lifecycle of the Aether API (FastAPI), Aether App (SvelteKit), and supporting infrastructure (MariaDB, Redis, Nginx).

## 🌐 Traffic Architecture

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
      ↓
Home Server Nginx  (SSL termination, domain routing)
      ↓                          ↓
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 round-robin)  (Docker DNS round-robin)
      ↓                          ↓
 ae_app replicas          ae_api replicas
```

**Key Improvements:**
- **Timezone Support:** All containers use the `TZ` variable from `.env` for consistent logging and database timestamps.
- **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 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
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
```

### 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
# CRITICAL: Set unique CONTAINER_ prefixes and AE_NETWORK_NAME for each stack
vim .env
```

### 3. Configure Data & Source Paths
The containers locate data and source code using absolute paths defined in your `.env` file. Ensure these variables point to the correct locations on your host system:
- **`AE_API_SRC`**: Path to your `aether_api_fastapi` repository.
- **`AE_APP_SRC`**: Path to your `aether_app_sveltekit` repository.
- **`HOSTED_FILES_SRC`**: Path to the physical storage for images/documents.
- **`HOSTED_TMP_SRC`**: Path for temporary file processing.

### 4. Certificates & Database
*   **SSL:** Place your wild-card certificates in `conf/certs/` (matching the filenames in `docker-compose.yml`).
*   **Database:** Use the restoration scripts (see below) to import a MariaDB snapshot.

---

## 🛠️ Management Commands

### Orchestration (Unified Stack)
```bash
docker compose up -d --build   # Build and start all services (Autonomous SvelteKit build)
docker compose down            # Stop all services
docker compose restart ae_app  # Restart the SvelteKit UI
docker compose restart ae_api  # Restart the FastAPI Backend
```

### Deployment Workflow
The SvelteKit application is built **inside** the container using `vite build --mode <env>`, which reads the corresponding `.env.<env>` file for `PUBLIC_` variables.

From `aether_app_sveltekit/`:
```bash
# Build Docker image locally
npm run build:docker:dev    # uses .env.dev
npm run build:docker:test   # uses .env.test
npm run build:docker:prod   # uses .env.prod

# Deploy to remote server (linode.oneskyit.com)
npm run deploy:remote:test
npm run deploy:remote:prod
```

Or via Makefile targets in this directory:
```bash
make build-docker-dev
make deploy-remote-prod
```

---

## 🗄️ Database Management (Physical Backups)
... (rest of the file remains the same) ...

The system uses physical hot backups via `mariabackup` for maximum speed and data integrity.

### User-Facing Scripts
These scripts are located in the root directory:

*   **`./backup_db.sh`**: Triggers an immediate hot backup. Results are stored in `backups/`.
*   **`./export_db.sh`**: Creates a "Conference Ready" backup in `backups/conference_export/` with host-user ownership.
*   **`./restore_db.sh [backup_file.gz]`**: Performs a full "Clean Slate" restoration.
    *   *Warning:* This stops MariaDB, archives current data, and resets `root` passwords to match your `.env`.
*   **`./check_and_import.sh`**: A watchdog script that monitors `backups/import/` for new snapshots and triggers automated restoration.

---

## 📂 Directory Map

*   **`conf/`**: Configuration templates for Nginx and Gunicorn. API config now lives in the `aether_api_fastapi` repo as `app/config.py` and reads settings directly from env vars.
*   **`logs/`**: Centralized logging for all containers. Automatic rotation is managed by the `ae_ops` service (7-day retention).
*   **`srv/`**: Mount points for data and source code (managed via symlinks).
*   **`scripts/`**: Internal automation logic.
*   **`backups/`**: Storage for MariaDB snapshots.

---

## 📝 Configuration Guidelines

### Environment Profiles (`COMPOSE_PROFILES`)
*   **`database`**: Includes MariaDB, phpMyAdmin, and the `ae_ops` maintenance service.
*   **App-Only**: Leave empty if connecting to a remote/shared database server.

### Aether Config ID (`AE_CFG_ID`)
Specifies the record from the `cfg` table to load during the API bootstrap process:
*   `1`: Default / Template
*   `5`: Home Development
*   `7`: Live Testing

---

## ⚠️ Security Notes
*   Never commit the `.env` file (it is ignored by git).
*   Ensure `AE_API_JWT_KEY` is a unique, high-entropy string in production.
*   The API prioritizes `.env` credentials over DB settings for core infrastructure (SMTP/DB) to prevent accidental lockouts.