b4866c2f23
Updated README.md to reflect V3 architecture, documented the physical database management suite, and finalized synchronization between env.default and active .env configuration.
103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# 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.
|