Deployment

Hanzo Commerce can be deployed in multiple ways depending on your infrastructure requirements, team size, and scaling needs.

Deployment Options

Docker

Containerized deployment with compose.yml for Commerce, Redis, Hanzo S3, and Meilisearch

Kubernetes

Production-grade orchestration with Helm charts, autoscaling, and high availability

Vercel

Deploy the Next.js storefront and docs to Vercel with edge functions and ISR

Self-Hosted

Run on bare metal or a VPS with systemd, Nginx, and Let's Encrypt

Infrastructure Requirements

Minimum (Development / Small Store)

Component	Requirement
CPU	2 cores
RAM	4 GB
Disk	20 GB SSD
Network	Public IP or reverse proxy

Recommended (Production)

Component	Requirement
CPU	4+ cores
RAM	8+ GB
Disk	100 GB SSD
Database	PostgreSQL 15+ (managed recommended)
Cache	Redis 7+
Search	Meilisearch or PostgreSQL FTS
Object Storage	S3-compatible (Hanzo S3, AWS S3, R2)

Environment Variables

All deployment methods share these core environment variables:

# Required
COMMERCE_DIR=/data                    # Data directory
DATABASE_URL=postgresql://...         # PostgreSQL connection string
HANZO_API_KEY=hk_live_...            # Hanzo platform API key

# Cache and Sessions
KV_URL=redis://redis:6379/0          # Redis connection URL

# Object Storage (uploads, media)
S3_URL=s3://key:secret@host/bucket   # S3-compatible storage URL

# Search (optional but recommended)
SEARCH_URL=http://meilisearch:7700   # Meilisearch URL

# Payments
STRIPE_SECRET_KEY=sk_live_...        # Stripe secret key
STRIPE_WEBHOOK_SECRET=whsec_...      # Stripe webhook signing secret

# Authentication
HANZO_CLIENT_ID=...                  # OAuth2 client ID
HANZO_CLIENT_SECRET=...              # OAuth2 client secret

# Analytics (optional)
CLICKHOUSE_URL=http://...:8123       # ClickHouse for analytics

# Server
COMMERCE_PORT=8090                   # HTTP listen port (default: 8090)
COMMERCE_HOST=0.0.0.0               # Bind address
COMMERCE_ENV=production              # Environment (development|production)

Health Checks

Commerce exposes health endpoints for orchestration and monitoring:

Endpoint	Purpose
`GET /health`	Basic liveness check -- returns 200 if the process is running
`GET /health/ready`	Readiness check -- returns 200 when all dependencies (DB, Redis) are connected
`GET /health/startup`	Startup probe -- returns 200 after initial migrations and warming

Example health check response:

{
  "status": "healthy",
  "version": "1.4.2",
  "uptime": "72h14m",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "search": "ok",
    "storage": "ok"
  }
}

Monitoring

Prometheus Metrics

Commerce exposes metrics at /metrics in Prometheus format:

commerce_http_requests_total -- request count by method, path, status

commerce_http_request_duration_seconds -- request latency histogram

commerce_orders_total -- order count by status

commerce_active_carts -- current active cart gauge

Structured Logging

Commerce logs in JSON format to stdout:

{"level":"info","ts":"2026-02-16T10:00:00Z","msg":"order.created","orderId":"order_abc123","total":5998}

Set the log level with COMMERCE_LOG_LEVEL (debug, info, warn, error).

Next Steps

Choose your deployment method from the options above, or start with Docker for the fastest path to production.

Docker

Kubernetes

Vercel

Self-Hosted

On this page