Deploy Vendure

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.

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.

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 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

Deployment Dependencies

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

Hardware Requirements for Self-Hosting Vendure

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.