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 both the server, which handles all incoming requests, and the worker, which processes background tasks, in a single process. While this setup is suitable for development, it is not optimal for production environments where background tasks can be long-running or resource-intensive.

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: