Deployment

Deployment Patterns

Single Process Deployment

Start World in application process. Workflows execute in the same process.

Best for: Small to medium workloads, development, simple apps.

// server.ts
import { World } from 'worlds-engine';

const world = new World({
  persistence: 'hybrid',
  minWorkers: 2
});

await world.start();

// Start your API server...

Multi-Process Deployment

Share .worlds-engine directory via network filesystem (NFS, EFS). Each process runs an independent world instance. Coordination happens through file-based queue.

Best for: Horizontal scaling, high availability.

// worker.ts
const world = new World({
  persistence: 'file', // Must use file persistence
  persistencePath: '/mnt/shared/.worlds-engine'
});

await world.start();

Container Deployment

Mount .worlds-engine as a persistent volume. Can run as single container or multiple with shared volume.

Best for: Kubernetes, Docker Swarm, cloud deployments.

Dockerfile:

FROM node:18-alpine

WORKDIR /app
COPY . .
RUN npm install
RUN npm run build

# Persist state
VOLUME /app/.worlds-engine

CMD ["node", "dist/server.js"]

docker-compose.yml:

services:
  app:
    build: .
    volumes:
      - worlds-data:/app/.worlds-engine

volumes:
  worlds-data:

Monitoring Integration

Prometheus

Expose metrics endpoint for Prometheus scraping:

import { convertToPrometheusFormat } from './utils';

app.get('/metrics', (req, res) => {
  const metrics = world.getMetrics();
  res.send(convertToPrometheusFormat(metrics));
});

Logging

Logs are written to console and .worlds-engine/logs directory with daily rotation.

Log Entry Structure:

{
  timestamp: number;
  level: 'debug' | 'info' | 'warn' | 'error';
  category: 'world' | 'worker' | 'workflow' | 'activity' | 'system';
  message: string;
  metadata?: Record<string, any>;
}

Migration Strategy

Workflow state format is versioned through history events. Breaking changes require migration scripts.

Migration Pattern:

1. Drain in-flight workflows (stop accepting new ones)
2. Shutdown World
3. Run migration script on .worlds-engine directory
4. Update code
5. Restart World

Backward compatibility is maintained within major versions.

Troubleshooting

Debugging Workflows

Inspect State:

const state = await world.query(workflowId);
console.log(state.history);
console.log(state.activities);
console.log(state.compensations);

Filter Logs:

const logs = await logger.queryLogs({
  category: 'workflow',
  level: 'error',
  since: Date.now() - 3600000 // Last hour
});

Quarantine Strategy

For problematic workflows that crash the system, use quarantine strategy to isolate them without losing state:

const problematic = workflow('debug', handler, {
  failureStrategy: 'quarantine'
});