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

Understanding this prevents configuration mistakes.

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 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.

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

---

🚀 Quick Start

1. Initialize Directory Structure

Create the base directory and clone this environment:

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

2. Configure Environment Settings

Copy the template and update it with your local paths and credentials:

cd /srv/env/aether/container_env
cp env.default .env
# Edit .env to match your host system (Paths, DB, Ports)
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)

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. You can control the build mode (which bakes in the correct PUBLIC_ variables) via the .env file:

• Set AE_APP_BUILD_MODE=staging for development/testing.
• Set AE_APP_BUILD_MODE=prod for production.

Then run:

docker compose up -d --build ae_app

---

🗄️ 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, Gunicorn, and the API.
• logs/: Centralized logging for all containers.
• 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.