---
title: "Deploy Vendure"
description: "Headless e-commerce backend with a GraphQL API and admin UI"
category: "Other"
url: https://railway.com/deploy/vendure-ecommerce
---

# Deploy Vendure

Headless e-commerce backend with a GraphQL API and admin UI

**[Deploy Vendure on Railway](https://railway.com/template/vendure-ecommerce)**

- **Creator:** A3A
- **Category:** Other
- **Total deploys:** 1

## Template content

### Redis https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/redis.svg

- **Image:** redis:8.2
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### mailpit https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/mailpit.svg

- **Image:** axllent/mailpit:latest
- **Health check:** /livez
- **Public domain:** Yes

### vendure-server https://assets.vendure.io/brand/logo-icon-vendure-blue.svg

- **Source:** https://github.com/gridalpha/vendure-railway
- **Public domain:** Yes

### vendure-worker https://assets.vendure.io/brand/logo-icon-vendure-blue.svg

- **Source:** https://github.com/gridalpha/vendure-railway

## Buckets

- **vendure-assets**

## Documentation

![Vendure logo](https://assets.vendure.io/shared/vendure-hero.jpeg)

# Deploy and Host Vendure on Railway

Vendure is an open-source headless commerce platform built with TypeScript, NestJS and GraphQL. It gives you a complete commerce backend — catalog, variants, collections, channels, promotions, tax and shipping zones, order state machines, payments and fulfilment — behind a Shop API for your storefront and an Admin API for your team. Everything is extensible in ordinary TypeScript, so teams fighting a hosted platform's data model can add custom fields, entities and business rules to the commerce core. It ships a React admin dashboard, so you have a back office on day one and only build the storefront.

This template runs Vendure the way its own scaling guide recommends. Self-host Vendure on Railway and you get a **server** exposing the Shop API, Admin API, dashboard and assets; a separate **worker** draining the job queue and running scheduled tasks; **PostgreSQL** as the system of record; **Redis** carrying the queue and the shared cache, which is what makes the two processes safe to run apart and to scale; an **object storage bucket** for product images; and **Mailpit** as a private SMTP endpoint, so email works before you wire up a relay. Both build from one repository, [gridalpha/vendure-railway](https://github.com/gridalpha/vendure-railway).

![Diagram of the Vendure server, worker, Postgres, Redis and Mailpit services on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1787729206/vendure-architecture.png)

## Getting Started with Vendure on Railway

The first boot creates the schema and seeds a working store — a default channel, tax and shipping zones, payment methods and 54 demo products with images — so there is no installer to click through. Open the server's public URL at `/dashboard` and sign in with the `SUPERADMIN_USERNAME` and `SUPERADMIN_PASSWORD` you set at deploy time. To confirm everything is wired up, open **Catalog → Products**: if the thumbnails render, object storage is connected and image transforms work. Then create a product and check **System → Job Queue** — `update-search-index` jobs reaching `COMPLETED` prove Redis and the worker are live. Email lands in Mailpit at its own public URL, behind the credentials in `MP_UI_AUTH`. For real mail, point the `SMTP_*` variables at your provider and set `STOREFRONT_URL` so email links resolve to your storefront, not the API host. Set `POPULATE_DEMO_PRODUCTS` to `false` before deploying to start empty.

![Vendure product catalogue listing furniture products with thumbnails](https://res.cloudinary.com/rroe4rtk/image/upload/v1787729211/vendure-product-catalogue.png)

![Vendure order detail showing a settled laptop purchase and tax summary](https://res.cloudinary.com/rroe4rtk/image/upload/v1787729212/vendure-order-detail.png)

![Vendure job queue listing completed search-index and email jobs](https://res.cloudinary.com/rroe4rtk/image/upload/v1787729217/vendure-job-queue.png)

## About Hosting Vendure

Vendure sits between a hosted SaaS platform and a from-scratch build: you own the data and the deployment, but you do not write order state machines, tax calculation or promotion logic yourself. Teams self-host it when a hosted platform's data model is the constraint — B2B pricing tiers, per-customer catalogues — or when order history should not live on someone else's infrastructure.

Key features:

- Shop and Admin GraphQL APIs, with a React dashboard on the same origin
- Multi-channel, multi-currency selling with per-channel pricing
- Custom fields and entities on core types, with the schema regenerated to match
- Plugins for payments, shipping, search, assets and scheduled work
- Role-based permissions, API keys, and a full order state machine

On Railway the server handles every HTTP request and streams assets out of the bucket. Anything slow — indexing, collection recalculation, email — goes to Redis as a job and is picked up by the worker, so an import never blocks a storefront request. Media lives in the bucket rather than on a disk, which is what lets the server run more than one replica.

## Why Deploy Vendure on Railway

Railway removes the operational work this architecture needs.

- PostgreSQL, Redis and object storage provisioned and wired up automatically
- Server and worker built from one repository, scaled independently
- Private networking, with only the API publicly routed
- Health checks on both processes, so a stalled worker is visible
- Deploys on every push to the source repository

## Common Use Cases

- **B2B and wholesale storefronts** needing customer-specific pricing and approvals
- **Composable commerce backends** behind a Next.js, Nuxt or mobile storefront
- **Multi-brand or multi-region catalogues** run as channels from one deployment
- **Migrations off hosted platforms** where the data model forces the move

## Dependencies for Vendure

- **vendure-server** — built from [gridalpha/vendure-railway](https://github.com/gridalpha/vendure-railway) on `node:22-bookworm-slim`; Shop API, Admin API, dashboard and assets on port 3000
- **vendure-worker** — the same image with `VENDURE_ROLE=worker`; job queue and scheduler, exposing only a health endpoint
- **PostgreSQL** — system of record for catalogue, customers and orders
- **Redis** — job queue and shared cache; both services must reach it
- **Object storage bucket** — product images and generated thumbnails
- **Mailpit** (`axllent/mailpit`) — captures email on private SMTP port 1025, behind a password-protected inbox

### Environment Variables Reference

| Variable | Purpose |
|---|---|
| `SUPERADMIN_USERNAME` / `SUPERADMIN_PASSWORD` | First admin, seeded on first boot only |
| `COOKIE_SECRET` | Session signing key; identical on server and worker |
| `VENDURE_ROLE` | `server` or `worker` — what the container runs |
| `REDIS_URL` | Enables the job queue and the Redis cache |
| `HARDEN_API` | `true` disables introspection and caps query complexity |
| `POPULATE_DEMO_PRODUCTS` | `false` skips the demo products on first boot |
| `STOREFRONT_URL` | Base URL for links inside customer emails |
| `MAX_QUERY_COMPLEXITY` | Shop API ceiling; raise it if a query is rejected |
| `REQUIRE_EMAIL_VERIFICATION` | Whether new customers confirm their address |

### Deployment Dependencies

- Source repo: 
- Upstream: 
- Docs:  — runtime is Node.js 22, PostgreSQL 16+, Redis 7+

## Hardware Requirements for Self-Hosting Vendure

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU per service | 2 vCPU server, 1 vCPU worker |
| RAM | 1 GB server, 512 MB worker | 2 GB server, 1 GB worker |
| Storage | Database only | Database plus object storage |
| Runtime | Node.js 20 | Node.js 22 |


## Self-Hosting Vendure

Vendure is a framework, not a prebuilt image, so a deployment starts as a project you generate and own. This creates one locally:

```
npx @vendure/create my-store
cd my-store
npm run dev
```

The generator writes `src/vendure-config.ts`, which holds the whole configuration. To run the same shape as this template, clone the source repository and build the image:

```
git clone https://github.com/gridalpha/vendure-railway
cd vendure-railway
docker build -t vendure-railway .
docker run -p 3000:3000 \
  -e DB_HOST=postgres -e DB_NAME=vendure \
  -e DB_USERNAME=postgres -e DB_PASSWORD=secret \
  -e REDIS_URL=redis://redis:6379 -e COOKIE_SECRET=change-me \
  -e SUPERADMIN_PASSWORD=change-me vendure-railway
```

Run a second container from the same image with `VENDURE_ROLE=worker` for the background tier.

## How Much Does Vendure Cost to Self-Host?

The Vendure core is open source under the GPLv3 licence and free to self-host, with no seat, order or revenue limits. Vendure sells a commercial licence and paid enterprise plugins on top, but nothing here depends on them. On Railway you pay only for the compute, database and storage these services use — a cost that tracks traffic, not sales.

## FAQ

**What is Vendure?**
An open-source headless commerce platform written in TypeScript on NestJS. It exposes a GraphQL Shop API for storefronts and an Admin API for back-office tools, and ships a React admin dashboard.

**What does this Railway template deploy?**
A Vendure server, a separate worker, PostgreSQL, Redis, an object storage bucket for media, and Mailpit for transactional email. Server and worker build from one public repository and are configured entirely through environment variables.

**Why does the template include Redis and a separate worker service?**
Vendure pushes search indexing, collection recalculation and email onto a job queue. Redis carries that queue and the shared cache, and the worker drains it, so a bulk import never slows storefront requests — the arrangement Vendure's own scaling guide describes.


**How do I use my own SMTP provider instead of Mailpit?**
Set `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER` and `SMTP_PASSWORD` on both services, set `EMAIL_FROM` to an address your provider accepts, and set `STOREFRONT_URL` so email links point at your storefront. You can then remove Mailpit.

**How do I connect a storefront to self-hosted Vendure?**
Point it at `https:///shop-api`. Vendure publishes a Next.js starter, and the API is plain GraphQL, so any client works. If a large query is rejected, raise `MAX_QUERY_COMPLEXITY`, or set `HARDEN_API` to `false` in development for introspection and a GraphQL explorer.

**How do I add custom fields or a plugin to self-hosted Vendure?**
Fork the repository and edit `src/vendure-config.ts`. Custom fields and new entities change the database schema, so run `npm run migrate` to generate a migration, commit it, and push — the server applies pending migrations on start.


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/vendure-ecommerce