Deploying Vendure

Introduction

Vendure is a modern, headless e-commerce framework built with TypeScript and Node.js. Designed for developers who need flexibility and control, Vendure provides a powerful GraphQL API that allows you to build custom storefronts while handling all the complex backend logic for products, orders, customers, and payments.

Key highlights of Vendure:

• Headless Architecture: GraphQL API-first design for ultimate frontend flexibility
• TypeScript Native: Built entirely in TypeScript for type safety and developer experience
• Plugin System: Extend functionality with a robust plugin architecture
• Admin UI: Modern Angular-based admin interface for store management
• Multi-Channel: Support multiple sales channels from a single installation
• Multi-Vendor: Built-in marketplace capabilities
• Payment Integrations: Support for Stripe, PayPal, Braintree, and custom providers
• Search: Elasticsearch integration for powerful product search
• Asset Management: Built-in image processing and CDN support

This guide walks through deploying Vendure on Klutch.sh using Docker, configuring the e-commerce platform, and setting up for production use.

Why Deploy Vendure on Klutch.sh

Deploying Vendure on Klutch.sh provides several advantages for e-commerce:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Vendure without complex orchestration. Push to GitHub, and your store deploys automatically.

Persistent Storage: Attach persistent volumes for your database, product images, and assets. Your store data survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for secure e-commerce transactions.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your store’s traffic and product catalog size.

Prerequisites

Before deploying Vendure on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Vendure configuration
• Basic familiarity with Docker and containerization concepts
• Understanding of GraphQL and headless commerce concepts
• A PostgreSQL database (can be deployed on Klutch.sh)

Understanding Vendure Architecture

Vendure consists of several components:

Server: The Node.js backend providing GraphQL APIs

Admin UI: Angular-based interface for store management

Shop API: Public GraphQL API for storefront applications

Admin API: GraphQL API for administrative operations

Worker: Background job processing for tasks like search indexing

Preparing Your Repository

Create a GitHub repository containing your Dockerfile and Vendure configuration.

Repository Structure

vendure-deploy/
├── Dockerfile
├── src/
│   ├── vendure-config.ts
│   └── index.ts
├── package.json
└── .dockerignore

Creating the Dockerfile

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy application code
COPY . .

# Build the application
RUN npm run build

# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000
ENV DB_HOST=${DB_HOST}
ENV DB_PORT=${DB_PORT:-5432}
ENV DB_NAME=${DB_NAME}
ENV DB_USERNAME=${DB_USERNAME}
ENV DB_PASSWORD=${DB_PASSWORD}
ENV COOKIE_SECRET=${COOKIE_SECRET}
ENV SUPERADMIN_USERNAME=${SUPERADMIN_USERNAME:-superadmin}
ENV SUPERADMIN_PASSWORD=${SUPERADMIN_PASSWORD}

# Create assets directory
RUN mkdir -p /app/static/assets

# Expose the server port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

# Start the server
CMD ["node", "dist/index.js"]

Creating vendure-config.ts

import {
    VendureConfig,
    DefaultSearchPlugin,
    DefaultJobQueuePlugin,
    DefaultAssetNamingStrategy,
} from '@vendure/core';
import { AssetServerPlugin } from '@vendure/asset-server-plugin';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';

export const config: VendureConfig = {
    apiOptions: {
        port: Number(process.env.PORT) || 3000,
        adminApiPath: 'admin-api',
        shopApiPath: 'shop-api',
    },
    authOptions: {
        cookieOptions: {
            secret: process.env.COOKIE_SECRET || 'change-me',
        },
        superadminCredentials: {
            identifier: process.env.SUPERADMIN_USERNAME || 'superadmin',
            password: process.env.SUPERADMIN_PASSWORD || 'superadmin',
        },
    },
    dbConnectionOptions: {
        type: 'postgres',
        host: process.env.DB_HOST,
        port: Number(process.env.DB_PORT) || 5432,
        database: process.env.DB_NAME,
        username: process.env.DB_USERNAME,
        password: process.env.DB_PASSWORD,
        synchronize: false,
    },
    plugins: [
        AssetServerPlugin.init({
            route: 'assets',
            assetUploadDir: '/app/static/assets',
        }),
        DefaultJobQueuePlugin.init({ useDatabaseForBuffer: true }),
        DefaultSearchPlugin.init({ bufferUpdates: false }),
        AdminUiPlugin.init({
            route: 'admin',
            port: 3002,
        }),
    ],
};

Environment Variables Reference

Variable	Required	Default	Description
DB_HOST	Yes	-	PostgreSQL host
DB_PORT	No	5432	PostgreSQL port
DB_NAME	Yes	-	Database name
DB_USERNAME	Yes	-	Database username
DB_PASSWORD	Yes	-	Database password
COOKIE_SECRET	Yes	-	Secret for session cookies
SUPERADMIN_USERNAME	No	superadmin	Admin username
SUPERADMIN_PASSWORD	Yes	-	Admin password

Deploying Vendure on Klutch.sh

Set Up PostgreSQL Database

Deploy a PostgreSQL instance on Klutch.sh or use an external database service. Create a database for Vendure.

Generate Secrets

Generate secure values for your deployment:

# Cookie secret
openssl rand -hex 32

# Admin password
openssl rand -base64 16

Push Your Repository to GitHub

Initialize your repository and push to GitHub with your Dockerfile and Vendure configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “vendure-store” or “ecommerce-api”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Vendure Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Add the following environment variables:

Variable	Value
DB_HOST	Your PostgreSQL hostname
DB_PORT	5432
DB_NAME	vendure
DB_USERNAME	Your database username
DB_PASSWORD	Your database password
COOKIE_SECRET	Your generated secret
SUPERADMIN_PASSWORD	Your admin password

Attach Persistent Volumes

Add the following volume:

Mount Path	Recommended Size	Purpose
/app/static/assets	20 GB	Product images and assets

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision an HTTPS certificate.

Access Vendure

Once deployment completes:

• Admin UI: https://your-app-name.klutch.sh/admin
• Shop API: https://your-app-name.klutch.sh/shop-api
• Admin API: https://your-app-name.klutch.sh/admin-api

Initial Configuration

Setting Up Your Store

1. Log in to the Admin UI with your superadmin credentials
2. Configure your default channel settings
3. Set up tax categories and rates
4. Configure shipping methods
5. Add payment methods

Adding Products

1. Navigate to Catalog > Products
2. Click Create Product
3. Enter product details, variants, and images
4. Set inventory levels and pricing
5. Publish the product

Managing Orders

1. Orders appear in Sales > Orders
2. Process orders through fulfillment workflows
3. Handle refunds and cancellations
4. Track shipping and delivery

Building a Storefront

Vendure provides GraphQL APIs for building custom storefronts:

Shop API Queries

# Get products
query GetProducts {
  products {
    items {
      id
      name
      description
      variants {
        price
        sku
      }
    }
  }
}

# Add to cart
mutation AddToCart($productVariantId: ID!, $quantity: Int!) {
  addItemToOrder(productVariantId: $productVariantId, quantity: $quantity) {
    ... on Order {
      id
      total
      lines {
        productVariant {
          name
        }
        quantity
      }
    }
  }
}

Additional Resources

• Vendure Official Website
• Vendure Documentation
• Vendure GitHub Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Vendure on Klutch.sh gives you a powerful, developer-friendly e-commerce platform with GraphQL APIs and a modern admin interface. The combination of Vendure’s headless architecture and Klutch.sh’s deployment simplicity means you can quickly build scalable online stores with complete frontend flexibility.