Docker Setup Guide

Deploy Aevum Encyclopedia locally or in production using Docker Compose. Full stack isolation, reproducible environments, and one-command orchestration.

📌 Prerequisites

Ensure you have Docker (20.10+) and Docker Compose (v2+) installed on your system. Administrative privileges may be required for certain operations.

1. Prerequisites & System Checks

Verify your Docker environment is ready before proceeding:

bash

docker --version
# Docker version 24.0.x, build abc1234

docker compose version
# Docker Compose version v2.20.x

2. Clone & Initialize Project

Fetch the latest stable release and navigate into the project directory:

bash

git clone https://github.com/aevum-encyclopedia/platform.git
cd platform
mkdir -p data/{db,redis,uploads,logs}

3. Environment Configuration

Copy the example environment file and configure your secrets:

bash

cp .env.example .env

Edit .env with your credentials. Key variables:

Variable	Description	Default
DB_HOST	PostgreSQL service name or IP	postgres
DB_PASSWORD	Database superuser password	CHANGE_ME
REDIS_URL	Cache & queue broker address	redis://redis:6379/0
AUTH_SECRET_KEY	JWT signing key (min 32 chars)	REQUIRED
ALLOWED_ORIGINS	CORS whitelisted domains	http://localhost:3000

⚠️ Security Notice

Never commit .env to version control. Use a secrets manager or vault solution for production deployments.

4. Build & Launch Services

Start the entire stack with Docker Compose. This will pull images, build custom services, and wire networking automatically:

bash

docker compose up -d --build

Monitor initialization logs:

bash

docker compose logs -f app worker scheduler

💡 First-Run Migration

The entrypoint automatically runs database migrations and seeds initial taxonomy. This takes ~30 seconds on standard hardware.

5. Verify Deployment

Once containers are healthy, access the platform at http://localhost:8080. Run the built-in healthcheck:

bash

curl -s http://localhost:8080/api/v1/health | jq .
{
  "status": "ok",
  "database": "connected",
  "cache": "connected",
  "queue_depth": 0,
  "version": "3.2.1"
}

6. Common Management Commands

bash

# Stop all services
docker compose down

# Restart a specific service
docker compose restart app

# Scale workers for heavy indexing
docker compose up -d --scale worker=3

# Execute shell inside container
docker compose exec app bash

# View real-time resource usage
docker stats

Troubleshooting

Permission Denied on volumes: Ensure your user has write access to the data/ directory or adjust Docker daemon storage driver.
Port 8080 already in use: Edit docker-compose.yml and change 8080:8080 to an available port.
Database connection refused: Wait for postgres container to fully initialize (check logs with docker compose logs postgres).
Out of memory during build: Limit parallel build processes via COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker compose build.

📚 Next Steps

Proceed to Environment Configuration for advanced tuning, or jump to Production Deployment for cluster orchestration.