Installation & Configuration

#System Requirements

#Installation Steps

1. Clone the Repository

   Begin by fetching the latest stable release from the official repository.

   bash 📋 Copy

   git clone https://github.com/aevum-encyclopedia/core.git
   cd core
   npm ci

2. Initialize Environment

   Copy the example configuration and generate secure tokens for your instance.

   bash 📋 Copy

   cp .env.example .env
   npx aevum-init:tokens

   💡 The aevum-init:tokens command auto-generates JWT secrets, encryption keys, and API tokens. Never commit .env to version control.

3. Start Services

   Launch the application stack. For development, use the integrated dev server. For production, use Docker Compose.

   bash 📋 Copy

   # Development mode
   npm run dev
   
   # Production (Docker)
   docker compose up -d

#Configuration

Core configuration is managed via environment variables. Below are the essential parameters for a functional instance.

Environment Variables (.env)

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/aevum_db
REDIS_URL=redis://localhost:6379
MONGODB_URI=mongodb://localhost:27017/aevum_search

# Security & Auth
JWT_SECRET=your_generated_secret_here
ENCRYPTION_KEY=your_encryption_key_here
CORS_ORIGINS=https://your-domain.com,https://app.your-domain.com

# AI & External Services
OPENAI_API_KEY=sk-...
VERIFICATION_ENDPOINT=https://verify.aevum.dev/v1

# Application
NODE_ENV=production
APP_PORT=3000
MAX_CONCURRENT_WORKERS=4

Database Migration

After configuring your database credentials, run the schema migrations and seed the initial taxonomy.

npm run db:migrate
npm run db:seed:taxonomy
npm run db:seed:admin

#Verification & Health Checks

Confirm your installation is running correctly by checking the system endpoints.

curl http://localhost:3000/api/health
# Expected response: {"status":"ok","version":"2.4.1","uptime":124,"services":{"db":"connected","cache":"connected","search":"ready"}}

Access the admin dashboard at http://localhost:3000/admin to verify UI rendering and index synchronization.

#Troubleshooting

• Port already in use: Change APP_PORT in .env or terminate the conflicting process.
• Database connection refused: Verify PostgreSQL is running and accept connections on the configured port. Check pg_hba.conf for authentication rules.
• Redis timeout errors: Ensure Redis is accessible. Run redis-cli ping to verify connectivity.
• Search index not building: Check MongoDB replica set status. Run npm run search:reindex --force to rebuild manually.
• Logs location: ./logs/app.log (development) • Docker: docker compose logs -f