8.2. Worker Mode of Medusa Instance

In this chapter, you'll learn about the different modes of running a Medusa instance and how to configure the mode.

What is Worker Mode?#

By default, the Medusa application runs in shared mode, which runs:

• server: the application server that handles incoming requests to the application's API routes.
• worker: the worker that processes background tasks. This includes scheduled jobs and subscribers.

While this setup is suitable for development, it is not optimal for production environments where background tasks can be long-running or resource-intensive.

Worker Mode in Production#

In a production environment, you should deploy two separate instances of your Medusa application:

1. A server instance that handles incoming requests to the application's API routes.
2. A worker instance that processes background tasks. This includes scheduled jobs and subscribers.

You don't need to set up different projects for each instance. Instead, you can configure the Medusa application to run in different modes based on environment variables, as you'll see later in this chapter.

This separation ensures that the server instance remains responsive to incoming requests, while the worker instance processes tasks in the background.

How to Set Worker Mode#

You can set the worker mode of your application using the projectConfig.workerMode configuration in the medusa-config.ts. The workerMode configuration accepts the following values:

• shared: (default) run the application in a single process, meaning the worker and server run in the same process.
• worker: run a worker process only.
• server: run the application server only.

Instead of creating different projects with different worker mode configurations, you can set the worker mode using an environment variable. Then, the worker mode configuration will change based on the environment variable.

For example, set the worker mode in medusa-config.ts to the following:

medusa-config.ts
1module.exports = defineConfig({2  projectConfig: {3    workerMode: process.env.WORKER_MODE || "shared",4    // ...5  },6  // ...7})

You set the worker mode configuration to the process.env.WORKER_MODE environment variable and set a default value of shared.

Then, in the deployed server Medusa instance, set WORKER_MODE to server, and in the worker Medusa instance, set WORKER_MODE to worker:

Disable Admin in Worker Mode#

Since the worker instance only processes background tasks, you should disable the admin interface in it. That will save resources in the worker instance.

To disable the admin interface, set the admin.disable configuration in the medusa-config.ts file:

medusa-config.ts
1module.exports = defineConfig({2  admin: {3    disable: process.env.ADMIN_DISABLED === "true" ||4      false,5  },6  // ...7})

Similar to before, you set the value in an environment variable, allowing you to enable or disable the admin interface based on the environment.

Then, in the deployed server Medusa instance, set ADMIN_DISABLED to false, and in the worker Medusa instance, set ADMIN_DISABLED to true:

Dividing Resources in Cluster Mode#

When running Medusa in cluster mode, you can specify the number or percentage of instances that are servers or workers by passing the --servers and --workers options:

Terminal
❯npx medusa start --cluster 4 --servers 25% --workers 75% # Use 4 CPU cores, with 25% as servers and 75% as workers❯npx medusa start --cluster 4 --servers 1 --workers 3       # Use 4 CPU cores, with 1 as server and 3 as workers❯npx medusa start --cluster 4 --servers 1 --workers 1      # Use 4 CPU cores, with 1 as server and 1 as worker (the remaining 2 will run in shared mode)

In the above snippet you can see the following examples:

• In the first example, 25% of the instances (1 out of 4) will run as servers, and 75% (3 out of 4) will run as workers.
• In the second example, 1 instance will run as a server, and 3 instances will run as workers.
• In the third example, 1 instance will run as a server, and 1 instance will run as a worker. The remaining 2 instances will run in shared mode