Installation

Prerequisites

Dependency	Version	Notes
Node.js	24+	Required for manual install
pnpm	9+	Package manager
MongoDB	7+	Must run as a replica set
Redis	7+	Used for caching, queues, and sessions
Docker	24+	Required for Docker install only

Option 1: Docker Compose (Recommended)

Docker Compose starts all services including MongoDB and Redis.

# Clone the repository
git clone <repo-url> ai-gateway
cd ai-gateway

# Copy environment file
cp .env.example .env

# Start all services
docker compose -f docker/docker-compose.yml up -d

This starts five containers:

Container	Port	Description
aigw-mongo-primary	27017	MongoDB with replica set auto-init
aigw-redis	6379	Redis with AOF persistence
aigw-server	3000	Gateway API server
aigw-worker	—	BullMQ background worker
aigw-admin	3001	Admin dashboard

Option 2: Manual Install

1. Start Infrastructure

You need MongoDB running as a replica set and Redis. If you have them installed locally:

# Start MongoDB as a replica set
mongod --replSet rs0 --bind_ip_all

# In another terminal, initialize the replica set
mongosh --eval "rs.initiate({_id:'rs0', members:[{_id:0, host:'localhost:27017'}]})"

# Start Redis
redis-server --appendonly yes

Or start only the infrastructure via Docker:

docker compose -f docker/docker-compose.yml up -d mongodb-primary redis

2. Install Dependencies

git clone <repo-url> ai-gateway
cd ai-gateway
pnpm install

3. Configure Environment

cp .env.example .env

Edit .env and set at minimum:

• JWT_SECRET — at least 16 characters, random string
• JWT_REFRESH_SECRET — at least 16 characters, random string
• ENCRYPTION_KEY — exactly 64 hex characters (256-bit key)

Generate secure values:

# Generate JWT secrets
node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"

# Generate encryption key
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

4. Build and Seed

# Build shared types (must be built first)
pnpm build:shared

# Build the server
pnpm build:server

# Seed the database with default roles and super admin
pnpm seed

5. Start Services

# Start all services (server + worker + admin)
pnpm dev

# Or start individually
pnpm dev:server    # Gateway API on port 3000
pnpm dev:worker    # Background worker
pnpm dev:admin     # Admin dashboard on port 3001

Verify Installation

Check the health endpoint:

curl http://localhost:3000/health

You should receive a JSON response with "status": "ok".

Check the Swagger docs:

http://localhost:3000/docs

Check the admin dashboard:

http://localhost:3001

Troubleshooting

MongoDB replica set errors: MongoDB must run as a replica set for transaction support. If you see connection errors, verify the replica set is initialized with mongosh --eval "rs.status()".

Permission denied on Docker volumes: On Linux, ensure your user is in the docker group or run with sudo.

Port conflicts: If ports 3000, 3001, 27017, or 6379 are in use, update the port mappings in docker-compose.yml or your .env file.