Skip to main content

Backend Server/Worker Mode

Medusa has a backend architecture that typically operates in two primary modes: Server mode and Worker mode.

The Server mode is where the main application logic runs. This mode is responsible for handling incoming HTTP requests (such as API calls) and managing overall business logic (e.g., user authentication, order processing, etc.).

The Worker mode is used for offloading long-running tasks or background jobs that are not ideal to run during an HTTP request. These tasks often include time-consuming operations such as sending emails, processing payments asynchronously, updating inventory, or generating reports.

We will use PM2: A process manager that can be used to run both server and worker instances and keep them running in the background.

# Install PM2 globally (for managing processes)
npm install -g pm2

Updating & Setting up for Production Mode​

To update existing installation

  • Copy the latest updated content for package.json file in root director from link
  • Delete the node_modules directory to prevent conflict and run the following commands to load latest dependencies, build and then start the development server
npm install
npm medusa build
npm run dev
  • For running production build run thses set of commands from root folder of your installation. Check this link for details on production mode.
cd .medusa/server && npm install
cp ../../.env .env.production # creates a production copy of .env
npm run start

Server Mode (Production)​

Now to start server mode, edit the .env.production file in the medusa backend folder and change parameter MEDUSA_WORKER_MODE

Note if required we need to enable admin along with server mode

Also keep default server port 9000 - Your NGINX reverse proxy will redirect here

Note the port setting here does not reflect when starting up the server so we need to specify the port when starting the servers

DISABLE_MEDUSA_ADMIN=false
MEDUSA_WORKER_MODE=server
PORT=9000

Start backend in server mode.

There are two ways to do this. We can either use process manager PM2 and trigger the server using below command

pm2 start npm --name "medusa-server" -- run start -- --port 9000

Or we can directly use the start command and make the bash available by using & disown

npm run start -- --port 9000 & disown

Worker Mode​

Now to start worker mode, edit the .env file in the medusa backend folder and change parameter MEDUSA_WORKER_MODE

Note for worker instance we dont need admin so disable the same. Also both server and worker instance cannot run on same port.

So here we changed the worker port to 5173

Note the port setting here does not reflect when starting up the server so we need to specify the port when starting the servers

DISABLE_MEDUSA_ADMIN=true
MEDUSA_WORKER_MODE=worker
PORT=5173

Start backend in worker mode

pm2 start npm --name "medusa-worker" -- run start -- --port 5173

or

npm run start -- --port 5173 & disown

When using PM2, you can view and manage these processes using PM2 commands

pm2 list         # Lists all running processes
pm2 logs         # View logs for both server and worker
pm2 logs medusa-server      # Server only log
pm2 restart medusa-server   # Restart the server process
pm2 restart medusa-worker   # Restart the worker process
pm2 stop medusa-worker      # Stops the worker process
pm2 kill         # kill all process