Running Vendure in production can feel overwhelming at first, especially when infrastructure is involved. In this article, we'll walk through how to deploy the headless e-commerce framework Vendure to a single VPS using Dokploy, keeping things as simple and practical as possible.

The focus will be on infrastructure: what components Vendure needs, how they fit together, and how to deploy them in a way that’s suitable for production. If you'd rather skip the explanations and just follow the steps, you can jump straight to the Github repository.

Video guide

Prerequisites

• This guide assumes you already have a VPS running somewhere with:
  • At least 4 GB memory.
  • Ubuntu or Debian installed. See Dokploy's documentation for information on the supported Linux distros.
• Make sure your server accepts traffic on ports the following ports:
  • 3000 (Dokploy)
  • 80 and 443 (HTTP and HTTPS)
  • 5432 (Postgres)
  • 6379 (Redis)

Install Dokploy

First we will be installing Dokploy. Dokploy is a platform that allows you to manage Docker containers via a UI on your VPS

• First, SSH in to your machine, and install Dokploy. Make sure you also complete the setup.
• By default, Docker will not prune log files, so you need to set up log file rotation to prevent ever growing log files. Follow the steps described here to do so.
• Go to http://<your-vps-ip>:3000 and log in to your Dokploy instance and enable 2FA: Profile > Enable 2fa in the top right corner.

Now that Dokploy is installed, we can go ahead and create a project named Vendure. This is where our services will be created: a main API instance, a Vendure worker, PostgreSQL and Redis.

Set up Postgres

Postgres will be the database where Vendure will store its data, products, collections, orders, etc.

Follow the steps described here to create a PostgreSQL database with Dokploy and expose it to the internet. You should restrict access to port 5432 to only allow your local IP address! This is usually done on the VPS provider level, but can also be done with a tool like ufw

Check if you can log in to the database from your local machine with pgsql or a tool like Beekeeper.

Set up Redis

Vendure offloads intensive tasks to a separate worker service and uses BullMQ to do so. BullMQ is a library that uses Redis as a job queue. Vendure has some nice documentation on the concept of its worker and job queue.

Setting up Redis is, just like Postgres, pretty straightforward using the Dokploy UI. The detailed steps are described here.

The same here as for Postgres: make sure you only allow access to port 6379 from your local IP address.

Setup Vendure

Now that we have Postgres and Redis set up, we can set up Vendure. First we will try to run Vendure locally to verify if Postgres and Redis are set up correctly.

• Fork and clone this repository
• Create an .env file in ./vendure/.env with the variables defined here.
• Run npm ci to install Vendure's dependencies.
• Run npx vite build to build Vendure's dashboard.
• We can now try to run the Vendure server with npm run dev:server
• Go to http://localhost:3000/dashboard to check if your server has started successfully.

If all is well, you should be able to log in. This means Vendure is configured correctly, and it can reach our database and Redis.

Build and push to Docker Hub.

We will use GitHub Actions to package our Vendure project into a Docker image and push it to Docker Hub. This means you will have to create a Docker Hub account. But don't worry, a free account is all we need.

Follow the steps here to set the correct environment variables in your GitHub secrets and enable GitHub Actions.

Now, when you push a change to your main branch, this GitHub action will build the Docker image and push it to Docker Hub.

As a final smoke test, check your Docker Hub account to see if the image exists, and note down the name.

Create the Vendure service in Dokploy

The final step for the Vendure API instance is to make Dokploy deploy the Docker image to our VPS. We need to create a service and set the correct settings in Dokploy for the service.

When you click Deploy in the General tab, Dokploy will pull the image from Docker Hub and run it on your VPS! Go to vendure.yourcustomdomain.io/dashboard to verify that Vendure is running.

Vendure Worker

The Vendure Worker service will use the same Docker image, so there's no need to repeat those steps. Configuring the worker service in Dokploy is similar to the main instance, with some minor differences.

After your worker has been deployed, your Vendure setup is complete! This is all you need to get Vendure up and running on your VPS.

For a truly production-ready environment, continue reading and apply the following final adjustments.

Load test

We have tested our 4 GB 2 vCPU instance to be capable of handling about 240 orders per minute before the p95 response time exceeds 500 ms.

You can read more on the test setup and how to load test your own environment with the provided script here.

Health checks for zero downtime between deploys

We can configure a health check endpoint to make Dokploy wait for our container to become ready before it migrates traffic to the newly deployed container. Without this, Dokploy might already send traffic to the container while Vendure is still bootstrapping the Node application.

By default Vendure exposes a /health endpoint that tells us if Vendure is ready to serve traffic. Follow the steps in the Dokploy Documentation to set the health check for the Vendure application to /health, so that we can have zero-downtime deployments.

Resource allocation explained

Setting resource limits per service prevents a single service from using all available CPU or, worse, causing an Out Of Memory error on your VPS! Luckily, Dokploy allow us to set CPU and memory limits per service.

An important rule of thumb is that the sum of all assigned memory in Dokploy services should never exceed the total amount of memory of your server.

You can safely oversubscribe CPU (and should) because it is time-shared. If multiple containers demand more CPU than the VPS has, the kernel does not kill them; it simply throttles them. Setting some CPU limits for some services is still a good idea, to prevent one service from consuming all available CPU for a longer time.

On our 2 vCPU and 4 GB memory instance, we will do the following:

This uses 3 GB of memory in total, leaving 1 GB for the OS, Dokploy and Docker itself.

These resource limits can be set in the Advanced tab of each service and are set in bytes and CPU nanoseconds:

• 0.5 CPU would be defined as 500000000
• 500 MB memory limit would be defined as 524288000

Scaling up

Once your server starts to get more traffic, you might want to increase the memory and CPU of your VPS. Node.js will benefit from more than one CPU for things like crypto and file system I/O, but because Node.js itself is single-threaded, you will eventually need to create multiple Vendure main instances in Dokploy to handle more traffic.

You can use the replica setting to increase the number of replicas of the Vendure main API service. This will make Dokploy spin up multiple replicas of the same Docker image, with the same config. Dokploy's Traefik will split traffic evenly between the replicas.

You can do the same for the Vendure worker service if needed.

Backups

Dokploy allows you to easily create backups to S3-compatible destinations. Dokploy supports both automatically creating backups of Postgres and volume backups for Vendure's assets.

Security

• Make sure to follow Dokploy's security recommendations.
• Only allow access to ports 5432 and 6379 from specific IP addresses. These ports are only exposed so that you can run your local Vendure against the live Postgres and Redis instances.
• You should set up resource alerts for the VPS as a whole with your provider. For example:
  • Notify me when CPU is above 80%
  • Notify me when Memory usage is above 80%
• Use a tool like Uptime Kuma to periodically check both Vendure's main and worker /health endpoints.

That's it! Feel free to reach out to me if you have any questions. Happy self-hosting!