Deployment topologies

MDK's runtime pieces — the ORK kernel, the App Node, and one or more Workers — can run together in a single process or be split across many. This is a packaging and operations choice, and it is independent of how MDK scales logically (adding Workers, adding sites). This page explains the two shapes and when to pick each.

The two shapes

• Single-process: ORK, the App Node, and every Worker run inside one Node.js heap and event loop. Lowest footprint, simplest to start, nothing external to supervise. This is the shape behind the single-process site example.
• Multiple processes (microservices): Each service runs as its own OS process or container, supervised by pm2 or Docker. This is the shape behind the microservices site example.

The trade-off

Pick single-process when:

• You are developing locally, running demos, or want a self-contained site for tests
• Footprint matters more than isolation (minimal or embedded deployments)
• You do not need supervisor-managed restarts

Pick multiple processes when:

• You want to allocate resources per service — CPU and memory limits per process or container
• You need to restart or scale one Worker independently of the others
• A Worker crash must not take down the App Node or its siblings (failure isolation)
• You are orchestrating many Workers across one or more hosts

Where worker.js fits

The multi-process shape is built on backend/core/mdk/worker.js, a shared process entry compatible with pm2, Docker, or a direct node worker.js. It is driven by environment variables (SERVICE, and for a Worker WORKER/TYPE/RACK) rather than CLI flags. One worker.js runs per service, and the supervisor (pm2 or Docker) owns its lifecycle and resource limits. The single-process shape instead calls the programmatic APIs (getOrk, startWorker, startAppNode) directly in one process. The standalone worker.js install pattern defines the per-Worker mechanics.

Relationship to scaling

Topology is orthogonal to scale. Logical scaling is about how many Workers and ORK kernels you run (parallel Workers, per-site kernels, multi-site oversight). Deployment topology is about how those processes are packaged on a given host. You choose both: for example, a production site typically runs multiple processes (this page) and multiple parallel Workers per kernel (scaling).

Next steps

Two example deployments are available:

• Single-process site — node index.js, everything in one process
• Microservices site — pm2 or Docker, one process per service