All jobs

Set Up Redis for a Medusa Backend

Yes. An agent registers the Redis event bus, workflow engine, caching and locking providers in your Medusa config, wires the variables, checks the boot, opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the backend's configuration before it registers a module. In a monorepo laid out like medusajs/dtc-starter, apps/backend/medusa-config.ts calls defineConfig with a projectConfig holding only databaseUrl and the http block (storeCors, adminCors, authCors, jwtSecret, cookieSecret); it has no modules array and no redisUrl. apps/backend/.env.template already lists REDIS_URL=redis://localhost:6379 beside the CORS and secret entries, so the variable exists but nothing reads it. apps/backend/package.json pins every @medusajs/* package at 2.22.2, including @medusajs/caching, and requires Node 22.23.4 or newer; src/modules/, src/subscribers/, src/workflows/ and src/jobs/ hold only their README files, and jest.config.js splits tests into integration:http, integration:modules and unit by TEST_TYPE. The workspace is pnpm 10.11.1 with Turborepo, and the one workflow, .github/workflows/update.yaml, runs the Medusa update action on a release event; nothing in CI boots the server.

With no Redis registered, Medusa falls back to in-process implementations: events, workflow state, the cache and locks live in the memory of one server process, which is fine for medusa develop and wrong the moment a second instance or a separate worker runs. The agent adds a modules array to medusa-config.ts with four entries, each reading its own variable so a deployment can split them later: @medusajs/medusa/event-bus-redis with redisUrl from EVENTS_REDIS_URL and jobOptions that remove completed and failed jobs after an hour or a thousand entries; @medusajs/medusa/workflow-engine-redis with redis.redisUrl from WE_REDIS_URL; @medusajs/medusa/caching with one provider, @medusajs/caching-redis, id caching-redis, is_default and redisUrl from CACHE_REDIS_URL; and @medusajs/medusa/locking with the @medusajs/medusa/locking-redis provider, id locking-redis, is_default and redisUrl from LOCKING_REDIS_URL. projectConfig.redisUrl is set from REDIS_URL so the HTTP session store moves to Redis too, with redisPrefix left at its default.

The variables are the part a reviewer will copy, so the agent updates .env.template with the four module URLs set to the same redis://localhost:6379 default as REDIS_URL, and adds WORKER_MODE=shared with a comment that a production deployment runs one server and one worker process from the same image with the same Redis. It also adds @medusajs/caching-redis to apps/backend/package.json with pnpm add, since the core package @medusajs/caching is present but the Redis provider is not, and checks pnpm-lock.yaml records it. AGENTS.md in the repository root already points at medusa-config.ts for module configuration, so the agent adds one row there naming the Redis variables.

To check the result the agent installs Redis and Postgres in its sandbox with apt-get, creates the database, runs pnpm --filter @dtc/backend exec medusa db:migrate, then starts medusa develop and reads the boot log for the Connection to Redis in module 'event-redis' established line and the equivalent lines for the workflow engine and the providers, and for no fallback warning. It then runs pnpm --filter @dtc/backend test:integration:http with TEST_TYPE set, which boots the app through @medusajs/test-utils against the same config, before opening the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Set up Redis for this Medusa backend. Read apps/backend/medusa-config.ts, apps/backend/.env.template, apps/backend/package.json, apps/backend/jest.config.js, apps/backend/integration-tests/setup.js, AGENTS.md, package.json, pnpm-workspace.yaml and turbo.json first. In medusa-config.ts add a modules array registering @medusajs/medusa/event-bus-redis with redisUrl from EVENTS_REDIS_URL and jobOptions that remove completed and failed jobs after 3600 seconds or 1000 entries, @medusajs/medusa/workflow-engine-redis with redis.redisUrl from WE_REDIS_URL, @medusajs/medusa/caching with the @medusajs/caching-redis provider as default reading CACHE_REDIS_URL, and @medusajs/medusa/locking with the @medusajs/medusa/locking-redis provider as default reading LOCKING_REDIS_URL; set projectConfig.redisUrl from REDIS_URL. Add @medusajs/caching-redis with pnpm add at the same version as the other @medusajs packages. Update .env.template with the new variables and WORKER_MODE with a comment on server and worker processes, and add a row to AGENTS.md. Install Redis and Postgres in the sandbox, run the migrations, start medusa develop and confirm the Redis connection lines for each module appear with no in-memory fallback warning, run the http integration tests, then open a pull request that lists each module, its variable and its default.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request changes apps/backend/medusa-config.ts, apps/backend/.env.template, apps/backend/package.json, pnpm-lock.yaml and AGENTS.md. Its description is a table of the four modules and the session store, each with the resolve path, the environment variable it reads and the local default, followed by the boot-log lines from the sandbox showing each Redis connection established, and the integration test summary.

It explains why the variables are separate even though they all point at one Redis locally: a deployment can give the event queue and the workflow engine a dedicated instance later without touching the config again. It also states what did not change: no custom module, subscriber, workflow or job was added, and the storefront was not touched.

Before merging, a reviewer sets the real Redis URLs in each environment's secrets, decides whether the jobOptions retention suits their event volume, and plans the switch from WORKER_MODE=shared to one server and one worker process, which the description describes but does not make.

Run it on every new Medusa project

A team that starts each store from the same template sends this body once per new repository from its own server, each POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own config: a backend that already registers the event bus gets only the modules it lacks, and one on a Medusa version before 2.11 gets the older @medusajs/medusa/cache-redis module instead of the caching provider, with the version named in the pull request.

After the first merge, an automation on the Project with a linear trigger on linear.issue.labeled, infra in config.labels, and the prompt "this issue names a Medusa module that needs its own Redis instance or different queue options; change its entry in medusa-config.ts and .env.template, check the boot log, and open a pull request" starts one run per labelled issue. The trigger adds the issue after the prompt and fills in nothing else.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A Medusa backend boots happily without Redis, which is the trap: subscribers fire, workflows run and the cache works, all inside one process, and the first symptom appears in production when a worker and a server stop seeing each other's events. Getting the four registrations right means knowing which modules are plain modules and which are providers inside a module, which variable each reads, and what the boot log says when a fallback is in use. The agent checks all of that against a real Redis in its sandbox.

The boot log, the migration output and the integration test run stay with the run, so a reviewer can see each connection line rather than trust the diff. A team that runs several stores from one template applies the same change to all of them at once, each in its own sandbox.

Frequently asked questions

Why four variables when there is one Redis?

Each module reads its own option, and the Medusa docs name a different variable for each (EVENTS_REDIS_URL, WE_REDIS_URL, CACHE_REDIS_URL, LOCKING_REDIS_URL). Locally they all default to the same redis://localhost:6379; in production the event queue and the workflow engine can move to a dedicated instance by changing one variable each.

What about the cache module I see in older guides?

@medusajs/medusa/cache-redis is the module Medusa used before 2.11, and it is deprecated in favour of the Caching Module with a Redis provider. On 2.22.2 the agent registers @medusajs/medusa/caching with @medusajs/caching-redis; on an older backend it registers the old module and says so in the pull request.

Does this split the server and the worker?

No. It adds WORKER_MODE=shared to .env.template with a comment describing the server and worker values, and the description explains the two-process layout, but the change itself only makes that layout possible by moving events, workflows, cache, locks and sessions out of process memory.

How is the configuration checked without a deployment?

The agent installs Redis and Postgres in its sandbox, runs the migrations, starts medusa develop and reads the boot log for each module's connection line, then runs the integration:http tests, which boot the app through @medusajs/test-utils with the same config. The log lines are quoted in the pull request.

More Medusa jobs

More jobs like this: Hand off a long task

Keep reading