Docker Deployment

Gatewyse provides a Docker Compose configuration that runs all services: the gateway server, background worker, admin dashboard, MongoDB, and Redis.

Quick Start

# Copy and configure environment
cp .env.example .env
# Edit .env with production values (see Configuration guide)

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

Services

The docker/docker-compose.yml defines five services:

Service	Image / Dockerfile	Port	Description
mongodb-primary	mongo:7	27017	MongoDB with automatic replica set initialization
redis	redis:7-alpine	6379	Redis with AOF persistence, 256MB memory limit
server	docker/Dockerfile.server	3000	Express API gateway
worker	docker/Dockerfile.worker	—	BullMQ background job processor
admin	docker/Dockerfile.admin	3001	Nuxt 4 admin dashboard

All services are connected via a dedicated aigw-net bridge network.

Health Checks

Both infrastructure services include health checks:

• MongoDB — runs rs.status() every 10 seconds, auto-initializes the replica set if needed (30-second start period)
• Redis — runs redis-cli ping every 10 seconds

The server and worker services use depends_on with condition: service_healthy to wait for infrastructure readiness.

Volumes

Two named volumes persist data across container restarts:

Volume	Mount Point	Purpose
mongo-primary-data	/data/db	MongoDB data files
redis-data	/data	Redis AOF persistence

Production Configuration

Environment Variables

For production, set these in your .env file or pass them directly:

NODE_ENV=production
JWT_SECRET=<random-64-char-string>
JWT_REFRESH_SECRET=<random-64-char-string>
ENCRYPTION_KEY=<random-64-hex-chars>
REDIS_PASSWORD=<strong-password>
SUPER_ADMIN_PASSWORD=<complex-password>

# License (EE) — required in production. Without these the server logs a
# fatal license error and exits with process.exit(1) at boot.
LICENSE_TOKEN=<ed25519-signed-jwt-from-platform>
LICENSE_PUBLIC_KEYS=<pem-key-1>;;<pem-key-2>

# Optional license tuning (defaults shown).
LICENSE_SERVER_URL=https://platform.example.com/api/v1/licenses
LICENSE_PHONE_HOME_INTERVAL_MS=86400000
LICENSE_GRACE_PERIOD_MS=604800000

LICENSE_TOKEN and LICENSE_PUBLIC_KEYS are required in production. LICENSE_SERVER_URL is optional — when unset the verifier runs in air-gapped mode (no phone-home). LICENSE_PHONE_HOME_INTERVAL_MS (default 24h) and LICENSE_GRACE_PERIOD_MS (default 7d) tune the revocation poller. See the Environment Variables reference for all options.

Resource Limits

Add resource constraints to your docker-compose.override.yml:

services:
  server:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

  worker:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M

  mongodb-primary:
    deploy:
      resources:
        limits:
          memory: 2G

  redis:
    deploy:
      resources:
        limits:
          memory: 256M

Redis Configuration

The default Redis configuration uses:

redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy noeviction

For production, set a Redis password by adding to the Redis service:

redis:
  command: redis-server --appendonly yes --maxmemory 512mb --maxmemory-policy noeviction --requirepass ${REDIS_PASSWORD}

MongoDB Security

For production, add authentication to MongoDB:

mongodb-primary:
  command: mongod --replSet rs0 --bind_ip_all --auth --keyFile /data/keyfile

Production Deployment

docker/docker-compose.yml is the dev/single-host stack. For production the repo ships additional compose and Swarm stack files plus helper scripts:

File / script	Purpose
docker/docker-compose.prod.yml (pnpm docker:prod)	Single-host production Compose stack.
docker/docker-stack.prod.yml (pnpm deploy:stack)	Full Docker Swarm stack (deployed under the stack name aigw).
docker/docker-stack.prod-light.yml (pnpm deploy:stack:light)	Lighter Swarm stack for smaller deployments.
pnpm deploy:stack:rm	Removes the aigw Swarm stack.
pnpm docker:build / pnpm docker:push	Build / build-and-push all five images via docker/build-and-push.sh.

The Swarm stacks add nginx reverse proxies (nginx.conf, nginx-docs.conf, nginx-website.conf), the docs and website services, and MongoDB authentication. Five Dockerfiles are built: Dockerfile.server, Dockerfile.worker, Dockerfile.admin, Dockerfile.docs, and Dockerfile.website.

Scaling Workers

The background worker handles 15 BullMQ queues (gateway requests, embedding and audio processing, audit logging, usage aggregation and tracking, health checks, cache embeddings, log cleanup and backup, free-tier reset, document processing, batch polling, batch webhooks, and file-registry sweeps). To scale workers horizontally:

docker compose -f docker/docker-compose.yml up -d --scale worker=3

Each worker instance processes jobs from all queues. BullMQ handles job distribution and locking via Redis.

Useful Commands

# View logs
docker compose -f docker/docker-compose.yml logs -f server

# Restart a single service
docker compose -f docker/docker-compose.yml restart server

# Stop all services
docker compose -f docker/docker-compose.yml down

# Stop and remove volumes (deletes all data)
docker compose -f docker/docker-compose.yml down -v

# Rebuild after code changes
docker compose -f docker/docker-compose.yml up -d --build