Deploys the official open-source Medusa 2.0 release and its Next.js starter storefront to Railway, with every service wired, seeded, and health-checked automatically.
An independent project by FUNKYTON, not affiliated with MedusaJS, Inc. or Railway. "Medusa" is a trademark of MedusaJS, Inc.
Selling wholesale, or hosting other people's shops? There are sibling templates.
B2B · Multi-vendor marketplace
One click provisions and connects every service (Postgres, Redis, MeiliSearch, S3-compatible storage, backend and storefront), runs the migrations, seeds the database, creates your admin user with a strong random password, and shares API keys between the services automatically. When the health checks go green, the store is live. You handle products; the template handles plumbing.
Updated to Medusa 2.19.0 on 31 August 2026.
Deployed more than 3,800 times since 2023, and over 1,100 of those stores are still serving customers today.
Seven services in one Railway project, plus whichever third-party integrations you configure.
The seventh, Bucket-proxy, is the one that needs explaining. Railway buckets
serve nothing publicly, so a product image saved to one cannot be loaded by a
browser. The proxy is a small Railway Function that answers public GET and
HEAD requests by reading from the bucket, and S3_FILE_URL points at it so
image URLs resolve. It is deliberately read-only: it never exposes PUT,
POST, PATCH or DELETE.
A monorepo combining the official open-source MedusaJS 2.0 backend with the Medusa team's Next.js starter storefront, pre-configured for one-click deployment on railway.app.
Medusa is used as published, with no fork and no patches to the core, so the official Medusa documentation applies as normal. What this template adds on top is the Railway deployment setup and a set of preconfigured integrations (MeiliSearch search, Stripe payments, Resend email, S3-compatible file storage), all built with Medusa's own module and plugin APIs.
Looking for official Medusa hosting? Medusa Cloud is the hosted platform built by the Medusa team, and it is what funds the open source project this template deploys. If you would rather someone else ran the infrastructure, start there.
Where to get help
- A deploy that will not come up, or anything about the Railway side: the template's thread on Railway Station. Other people running this template read it, so an answer there helps the next person too.
- A bug in this repo, or a change you want: open an issue.
- Medusa itself, how a module works or how to build on it: the official docs and Medusa's own community channels.
| This template | Doing it by hand | |
|---|---|---|
| Time to a running store | Minutes | Half a day, and longer the first time |
| Seven services provisioned and networked | One click | Seven services to create, and the connection strings to copy between them |
| Migrations and seed data | Run automatically on first boot | medusa db:migrate, then write or adapt a seed script |
| Admin user | Created for you with a random password | Create it over the CLI after the database is up |
| Publishable API key | Generated and handed to the storefront automatically | Create it in the admin, then paste it into the storefront's environment |
| MeiliSearch | Provisioned, keyed, and the catalogue indexed | Install and configure the plugin, mint a search-only key, wire the storefront |
| Stripe, Resend, S3 | Configuration slots already wired, add your keys | Install and register each provider yourself |
| Health checks | Configured per service | Yours to add |
| Staying current | Pull the repo and redeploy | Yours to track |
Nothing here is magic, and none of it is locked in. It is the same Medusa you would install by hand, with the setup already done.
- S3-compatible file storage. Uses Medusa's stock S3 file provider, and works with any S3-compatible object storage: Railway buckets, AWS S3, Cloudflare R2, MinIO. Configure with the
S3_*environment variables (seebackend/.env.template). LegacyMINIO_*variables from older deployments of this template are still supported as a fallback (ignored as soon as anyS3_*variable is set). Note: the bucket must already exist and, for product images, allow public read (via a bucket policy). The backend does not create buckets or set policies. Uploads are sent without ACL headers by default (compatible with Railway buckets, R2 and new AWS buckets); setS3_ACL=public-readonly for legacy ACL-based buckets. - Resend email. Order confirmations, admin invites and password resets, as react-email templates you can edit and preview locally with
pnpm email:dev. Watch setup video. Special thanks to aleciavogel for the Resend notification service and react-email implementation. README - Stripe payments. Watch setup video
- MeiliSearch by Rokmohar. Adds product search to your store, and is configured automatically when deployed from the Railway template. For non-Railway setups: watch setup video.
All four are optional. A store deploys and runs without any of them; each one switches on when its environment variables are present.
Same one-click Railway setup, a different commerce model underneath. Both are maintained here alongside this one.
| Template | Fits when | |
|---|---|---|
| Medusa B2B | You sell wholesale. Company accounts with employees and spending limits, quote requests, and approvals before an order goes through. A Railway distribution of the official Medusa B2B starter. | Deploy |
| MercurJS Marketplace | You host other people's shops. Many sellers on one storefront, each with their own vendor dashboard, and an owner admin above them. Built on Medusa. | Deploy |
This template is the plain one: a single seller, a single storefront. Start here unless you recognised yourself above.
There is also a trial version of this same template, cut down to four services so it fits inside Railway's free tier. It leaves out search and object storage, so treat it as a way to see what you get for free rather than as somewhere to build a shop. Move to the full template above when you want to sell something.
Local infrastructure with docker compose (optional, recommended)
The repository root contains a docker-compose.yml that mirrors the services provisioned by the Railway template: postgres, redis, meilisearch and an S3-compatible object store (MinIO, standing in for a Railway bucket).
docker compose up -dstarts everything. A one-shot init job creates a publicmedusa-mediabucket automatically.- The commented
S3_*andMEILISEARCH_*values inbackend/.env.templatematch these services. Uncomment them in yourbackend/.envto enable file storage and search locally. - MinIO console: http://localhost:9005 (login:
medusa/supersecret), MeiliSearch: http://localhost:7700.
Backend
Video instructions: https://youtu.be/PPxenu7IjGM
cd backend
cp .env.template .env # then read it, the top of the file matters
pnpm install
pnpm ib # migrate and seed
pnpm dev # API on :9000, admin dashboard on :9000/appTo connect to your deployed database from your local machine, copy the DATABASE_URL value from Railway into your .env. Run pnpm ib only against a database you are willing to seed.
pnpm build && pnpm start compiles the project and runs from the compiled source, which is what Railway does. Use it to reproduce a deploy-only problem.
More detail in backend/README.md.
Storefront
Video instructions: https://youtu.be/PPxenu7IjGM
cd storefront
cp .env.local.template .env.local
pnpm install
pnpm dev # http://localhost:8000A running backend on port 9000 is required. The storefront fetches its publishable API key from the backend at boot, so next build on its own will not work.
More detail in storefront/README.md.
Requirements
- Node 22.12 or later. Both packages carry a
.nvmrc. - pnpm. This project is pnpm-only: the build scripts call pnpm directly, so an npm or yarn install gets you a tree that works locally and a deploy that fails.
- Postgres. Required. Set up automatically by the Railway template.
- Redis. Optional, falls back to a simulated in-memory bus. Set up automatically by the Railway template.
- S3-compatible storage. Optional, falls back to local disk, which is ephemeral on Railway. Set up automatically by the Railway template.
- MeiliSearch. Optional, and needs server 1.20 or later. Set up automatically by the Railway template.
No, it is an independent project by FUNKYTON. It deploys the official open-source Medusa release as published, with no fork and no patches to the core, so the official Medusa docs apply to your store exactly as written. What the template adds is the Railway deployment setup and the preconfigured integrations listed above.
The whole stack idles at 595 MB of memory, which is roughly $7 a month of Railway resources for a low-traffic store. Railway bills per second for what a service actually uses rather than for what you allocate to it, so a quiet shop costs very little to keep online.
At that level the plan fee is most of the bill, not the servers. Hobby is $5 a month including $5 of usage, which puts a quiet store near $7 all in. Pro is $20 including $20 of usage, absorbing the resource cost entirely. Real deployments of this template have sat between $20 and $25 a month on Pro.
Per-service memory and CPU limits let you cap it further, with the catch that a CPU limit makes the store slower while a memory limit set too low restarts it mid-request.
Per-service measurements, the full arithmetic, and how to tune it
Yes. R2 is S3-compatible, so it uses the same S3_* variables as everything else. Set S3_REGION=auto, leave S3_ACL unset (R2 rejects ACL headers), and give the bucket public read access with a bucket policy rather than per-object ACLs. The same applies to Railway buckets and new AWS buckets.
No. Every integration is optional and each one switches on only when its environment variables are present. Without Stripe the checkout offers manual payment; without Resend or SendGrid, no order confirmations are sent. You can add either later without redeploying from scratch.
No. This project is pnpm-only. backend/src/scripts/postBuild.js calls pnpm i --frozen-lockfile directly when assembling the production server, so an npm or yarn install gives you a tree that works locally and a deploy that fails.
Yes, that is the point. The homepage hero ships as a visibly dashed "example section" so you can tell the template's filler from your own work at a glance, and deleting it is a two-line change. The storefront is a standard Next.js App Router project with Tailwind.
- CONTRIBUTING.md covers setup, the QA test suite, and what gets merged quickly.
- SECURITY.md covers how to report a vulnerability privately, and the two settings every deployer owns.
- Licensed MIT.
If this template saved you a day, sponsoring keeps it maintained.
- How to set up credit card payment with the Stripe payment module: https://youtu.be/dcSOpIzc1Og
- https://funkyton.com/medusajs-2-0-is-finally-here/#succuessfully-deployed-whats-next
Interested in digital independence through self-hosted open source? Take a look at My Own Suite, a private cloud you run yourself: passwords, photos, files, documents and calendars, all on hardware you control. Free and open source under AGPL-3.0.
Website · Getting started · GitHub
