OSIT-AE-Docker-Env/README.md

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:

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

3. Setup Persistent Data & Symlinks

The containers expect data and source code to be available in the srv/ directory via symlinks:

# 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

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

Branch Management

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.