# Aether Framework - Docker Environment

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

## 🚀 Quick Start

### 1. 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
```

### 2. Configure Environment Settings
Copy the template and update it with your local paths and credentials:
```bash
cd /srv/env/aether/container_env
cp env.default .env
# Edit .env to match your host system
vim .env 
```

### 3. Setup Persistent Data & Symlinks
The containers expect data and source code to be available in the `srv/` directory via symlinks:
```bash
# Link your local source code
ln -s ~/OSIT_dev/aether_api_fastapi srv/aether_api
ln -s ~/OSIT_dev/aether_app_sveltekit srv/aether_app

# Link physical file storage
ln -s /mnt/data/aether/hosted_files srv/hosted_files
ln -s /mnt/data/aether/hosted_tmp srv/hosted_tmp
```

### 4. Certificates & Database
*   **SSL:** Place your Let's Encrypt certificates in `conf/certs/`.
*   **Database:** Use the restoration scripts (see below) to import a MariaDB snapshot.

---

## 🛠️ Management Commands

### Orchestration
```bash
docker compose up -d           # Start all services
docker compose down            # Stop all services
docker compose restart ae_api  # Restart specific service
```

### Branch Management
```bash
git pull --all
git switch development
docker compose up -d --build
```

---

## 🗄️ Database Management (Physical Backups)

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.