Deployment Guide

Deployment Architecture

Aevum Encyclopedia follows a microservices architecture with stateless API workers, distributed caching, and pluggable storage backends. The deployment bundle includes:

• Core API – REST & GraphQL endpoints
• Search Indexer – Vector & keyword search pipeline
• CDN Edge Workers – Static asset & response caching
• Admin Dashboard – Content moderation & analytics

Prerequisites

Quick Start (5-Minute Deploy)

Spin up a development instance locally for testing or staging environments.

# Clone repository
git clone https://github.com/aevum-encyclopedia/platform.git
cd platform

# Install dependencies & build
npm install && npm run build

# Initialize database
npm run db:migrate

# Start services
npm start

Access at http://localhost:3000. Default credentials: admin@localhost.com / changeme123

Environment Configuration

Copy .env.example to .env and configure the following variables:

AEVUM_DB_URL="postgresql://user:pass@db-host:5432/aevum_prod"
REDIS_URL="redis://:auth@cache-host:6379/0"
AEVUM_SECRET_KEY="your-32-byte-secure-key-here"
STORAGE_PROVIDER="s3"
AWS_ACCESS_KEY_ID="key"
AWS_SECRET_ACCESS_KEY="secret"
AWS_REGION="us-east-1"
AWS_BUCKET="aevum-media-prod"

Docker Deployment

Use the official Docker Compose setup for containerized deployments.

version: '3.9'
services:
  api:
    image: ghcr.io/aevum/platform:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    depends_on:
      - db
      - redis
    env_file: .env

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: aevum
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redisdata:/data

volumes:
  pgdata:
  redisdata:

Run with docker compose up -d. Verify health at /healthz endpoint.

Kubernetes & Helm

For production-scale deployments, use our official Helm chart:

# Add repository
helm repo add aevum https://charts.aevum.com
helm repo update

# Deploy with custom values
helm install aevum-prod aevum/encyclopedia \
  --set image.tag=v3.2.1 \
  --set replicaCount=3 \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=encyclopedia.example.com \
  -f values-prod.yaml

The chart includes autoscaling (HPA), persistent volumes, service meshes, and Prometheus metrics by default.

CI/CD Pipeline

Automate builds, tests, and deployments with GitHub Actions:

name: Deploy Aevum Platform
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run test
      - run: npm run build
      - uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/aevum/platform:${{ github.sha }}
      - run: helm upgrade --install aevum ./chart --set image.tag=${{ github.sha }}

Monitoring & Logs

Aevum exposes OpenTelemetry metrics and structured JSON logs out-of-the-box.

Health Endpoints

• GET /healthz – Liveness probe (returns 200 when ready)
• GET /readyz – Readiness probe (checks DB & Redis connectivity)
• GET /metrics – Prometheus format metrics (CPU, memory, request latency, cache hit ratio)

Troubleshooting

Connection Refused on Port 3000

Ensure Redis and PostgreSQL are running and reachable. Check REDIS_URL and AEVUM_DB_URL in .env.

Slow Search Indexing

Increase worker concurrency: set SEARCH_INDEX_CONCURRENCY=8. Ensure disk IOPS > 3000 for NVMe storage.

SSL/TLS Handshake Failures

If using reverse proxy (Nginx/Traefik), add proxy_set_header X-Forwarded-Proto https; and configure TRUST_PROXY=true.

For advanced support, check our knowledge base or join the DevOps Discord.