Deployment Overview

Overview

NexusCommerce supports two production deployment paths. Both use the same Docker images built from multi-stage Dockerfiles, and both rely on Supabase Cloud for the primary database and authentication.

Docker Compose + VPS is the recommended starting path for teams with 1-10 tenants. A single server runs all services behind a Caddy reverse proxy with automatic TLS.

Kubernetes + Helm is the scaling path for 100+ tenants. The Helm chart includes horizontal pod autoscalers, StatefulSets for data services, and nginx-ingress with cert-manager TLS.

Key Concepts

Container Images — Three Docker images are built from the monorepo:

Supabase Cloud — The database, auth, storage, and realtime are hosted on Supabase Cloud. No PostgreSQL container is needed in production.

Supporting Services — Redis (job queue), ClickHouse (analytics), and Grafana (monitoring) run alongside the application services.

Getting Started

1. Choose your deployment path:
   • Docker Compose — Single-server VPS deployment
   • Kubernetes — Cluster deployment with Helm
2. Set up CI/CD to automate builds and deployments

Features

Architecture

Internet
  │
  ▼
Caddy / Ingress (TLS termination)
  ├── /api/v1/*  → API (NestJS, port 3001)
  ├── /docs*     → API (Swagger)
  └── /*         → Web (Next.js, port 3000)

Internal:
  API → Redis (job queue)
  API → ClickHouse (analytics)
  API → Workers (AI jobs, port 8000)
  Grafana → ClickHouse + Redis (dashboards)

Image Registry

Images are pushed to GitHub Container Registry (ghcr.io) by the CI/CD pipeline. Each push to main produces images tagged with both sha-<short> and latest.

Environment Variables

All deployment methods use the same set of environment variables. See infrastructure/compose/.env.production.template for the full list with documentation.

Required variables: