Deployment

Bootstrap the host with ./install.sh (or installation/installation.sh), run Quan ERP with Docker Compose, ship plugins from build → available → installed, and harden staging / production.

Overview

Quark ERP / Quan ERP deploys as a base stack (Postgres, Redis, backend, frontend) plus versioned plugins. On a fresh server, use the install script to prepare Docker, Nginx, and start compose. You develop plugins under plugins/, build them into available-plugins/, then activate them through the ERP UI into installed-plugins/. The base images and @quan-erp/* packages must stay on the same version line.

installation/ — ./install.sh (or installation.sh) for host bootstrap + compose start/stop
docker-compose.yaml — Postgres, Redis, backend, frontend
plugins/ — source; quan-erp CLI builds into available-plugins/
ERP UI install — copies / activates into installed-plugins/
Never SQL-seed the module table against UAT or production

1. Host bootstrap (./install.sh)

Server deployments ship an installation helper next to the production docker-compose.yaml (folder installation/). Run it as a normal user — not with sudo / as root. The script installs Docker Engine, the Compose plugin, and Nginx, then can start or stop the stack.

Commands: install | start | stop (see ./install.sh --help)
Do not run as root — the script uses sudo only where needed (packages, systemctl, docker group)
install — detects Ubuntu/Debian or RHEL-family, installs Docker + Compose plugin + Nginx, enables services, adds your user to the docker group
start — docker compose up -d for the stack next to installation/
stop — docker compose stop for the same compose file
Supported OS: Ubuntu, Debian, RHEL, CentOS, Fedora, Rocky, AlmaLinux
After install, you may need a new shell (or re-login) so the docker group membership applies without sudo

SHTerminal

cd installation
chmod +x ./install.sh   # or ./installation.sh

# One-time host setup (Docker + Compose + Nginx)
./install.sh install

# Start compose services
./install.sh start

# Stop compose services
./install.sh stop

2. Base stack (Docker Compose)

For local template work, start under base/ with compose directly. On a server prepared with ./install.sh, prefer ./install.sh start so host helpers run before up -d. The example stack is four services on a shared bridge network: db (Postgres), redis, backend, and frontend. Backend talks to Postgres and Redis by compose service name.

Inside containers, hosts are compose service names (db, redis) — never localhost for cross-service traffic
Typical volumes: ./data (db / redis / app data), ./available-plugins, ./backend/installed-plugins, ./backend/logs
Match BASE_VERSION / image tags (base-backend, base-frontend) with plugin @quan-erp/* versions
Template passwords and token secrets are for local/dev only — rotate before any shared environment

SHLocal template

cd base
docker compose up -d
docker compose ps

SHServer (via install script)

cd installation
./install.sh start
./install.sh stop

2b. Example docker-compose.yaml

Copy this local/dev template, then replace every change-me value, set VITE_BACKEND_API to a browser-reachable URL, and point image tags / BASE_VERSION at your release line. Backend connects directly to Postgres (db:5432).

DATABASE_HOST / DB_HOST=db and DB_PORT=5432 — direct Postgres, no pooler in this template
Optional: OPENAI_* / FIREBASE_CONFIG — set only when those integrations are required; never commit real private keys

YAMLdocker-compose.yaml

services:
  db:
    image: postgres:17
    container_name: postgres
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: quan-erp
    ports:
      - "5432:5432"
    volumes:
      - ./data/db-data:/var/lib/postgresql/data
    networks:
      - app-network

  redis:
    image: redis:7
    container_name: quanerp-redis
    restart: unless-stopped
    ports:
      - "6379:6379"
    command: >
      redis-server
      --requirepass "change-me"
      --appendonly yes
    volumes:
      - ./data/redis:/data
    networks:
      - app-network
    healthcheck:
      test: ["CMD", "redis-cli", "ping", "-a", "change-me"]
      interval: 5s
      timeout: 2s
      retries: 5

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    image: theparadance/quan-erp-base-backend:1.0.0
    restart: unless-stopped
    platform: linux/amd64
    container_name: backend
    ports:
      - "8080:8080"
      - "8081:8081"
    environment:
      NODE_ENV: production
      MODE: dev
      BASE_VERSION: 1.0.0
      ORGANIZATION_ID: quan-erp

      FRONTEND_URL: http://localhost
      BACKEND_URL: http://localhost:8080
      DEV_TOOL_URL: http://localhost:8081
      PLUGIN_SERVER_URL: http://localhost:8082

      ACCESS_TOKEN_SECRET: change-me
      ACCESS_TOKEN_SECRET_EXPIRATION_TIME: 15m
      REFRESH_TOKEN_SECRET: change-me
      REFRESH_TOKEN_SECRET_EXPIRATION_TIME: 30d

      DATABASE_HOST: db
      DB_HOST: db
      DB_USERNAME: postgres
      DB_PASSWORD: change-me
      DB_PORT: 5432
      DB_SCHEMA: quan-erp
      DB_SYNC: true

      REDIS_HOST: redis
      REDIS_PORT: 6379
      REDIS_PASSWORD: change-me

      CLUSTER_MODE: false
      CLUSTER_MAX_COUNT: 2
      ENV_ENCRYPTION_KEY: change-me-32-char-hex-or-secret
      FIREBASE_CONFIG: ''

      OPENAI_BASE_URL: https://api.deepseek.com
      OPENAI_API_KEY: <sk-key>

      CORS_ALLOWED_ORIGINS: http://localhost:3000,http://127.0.0.1:3000,http://localhost,https://localhost

      AVAILABLE_PLUGINS_FOLDER: /app/available-plugins
      INSTALLED_PLUGINS_FOLDER: /app/installed-plugins
      APP_DATA_FOLDER: /app/data/data/
      UPLOAD_FILE_TEMP_FOLDER: /app/data/temp
      UPLOAD_FILE_FOLDER: /app/data/data/
      PLUGINS_ENV_FILE: /app/data/data/plugin.env.json
      RUNNER_FLOW_FILE: /app/data/data/workflows/

      ROOT_ADMIN_USERNAME: admin
      ROOT_ADMIN_PASSWORD: change-me
      DEVELOPER_CONFIG_PASSWORD: change-me

      MAX_USER_LIMIT: 5
      MAX_ACTIVE_USER_LIMIT: 5
      MAX_USER_SESSION_LIMIT_PER_USER: 1
      MAX_ORGANIZATION_BRANCH: 1
      MAX_ROLE_LIMIT: 5
      MAX_SUBSCRIPTION_GRACE_PERIOD_DAYS: 14
      SUBSCRIPTION_END_DATE: '2099-01-01'
    volumes:
      - ./backend/installed-plugins:/app/installed-plugins
      - ./data:/app/data
      - ./backend/logs:/app/logs
      - ./available-plugins:/app/available-plugins
    depends_on:
      - db
      - redis
    networks:
      - app-network
    dns:
      - 1.1.1.1
      - 8.8.8.8

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    image: theparadance/quan-erp-base-frontend:1.0.0
    restart: unless-stopped
    platform: linux/amd64
    container_name: frontend
    environment:
      VITE_BACKEND_API: http://localhost:8080
      VITE_MODE: dev
    ports:
      - "80:80"
    volumes:
      - ./data/frontend/web-env.json:/usr/share/nginx/html/web-env.json
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

3. Services & ports

Default template wiring (adjust for your host / reverse proxy). Prefer not publishing db / redis to the public internet on real servers.

db (postgres:17) — host 5432 → container 5432; backend sets DATABASE_HOST / DB_HOST=db and DB_PORT=5432; POSTGRES_DB / schema quan-erp; volume ./data/db-data
redis — host 6379 → 6379; REDIS_HOST=redis with REDIS_PASSWORD; volume ./data/redis
backend — :8080 (BACKEND_URL / API), :8081 (DEV_TOOL_URL); volumes for available-plugins, installed-plugins, ./data, logs
frontend — :80; set VITE_BACKEND_API to a URL the browser can reach (LAN IP or public hostname, not only localhost inside Docker)
Nginx on the host — installed by ./install.sh install for TLS / reverse proxy in front of frontend (and optionally API)

4. Deploy plugins

Plugins are not baked into the base images. Build them, stage them as available, then install through the product UI (or distribute a pack archive).

Build output → available-plugins/<name>/<version>/ (or base/available-plugins/ in the Node template)
After UI install → installed-plugins/<name>/ (or base/backend/installed-plugins/)
Backend loads installed plugins whose module row is marked installed
Frontend loads each installed plugin’s module.js and calls register(AppRegistry)
Local/dev only: insert a module row so the plugin appears in the UI — never against UAT/prod

TSBuild & stage

# From repo root
quan-erp build:prod sample-es
# Continuous during development
quan-erp watch sample-es

# Distributable zip (frontend + backend + metadata)
quan-erp pack:prod sample-es
quan-erp pack:prod sample-es ./dist-archives

5. Version alignment

Keep the platform and plugins on one version line to avoid runtime breaks.

All @quan-erp/* deps in plugin package.json share the same version as the base images
docker-compose image tags (base-backend, base-frontend) and BASE_VERSION stay in sync
module.metadata.json pluginVersion / requiredBasedVersion must match what you built and install
After upgrading base images, rebuild plugins against the matching @quan-erp/* packages

6. Environment configuration

Infrastructure settings come from compose environment blocks (and optional .env). Plugin-specific operator settings use @InjectEnv and should not require a redeploy when changed from the ERP UI. See Documentation → Backend → Environment variables for the full key list.

DB_* / DATABASE_HOST — use db (port 5432) in the example stack; DB_SCHEMA matches POSTGRES_DB (e.g. quan-erp)
REDIS_HOST / REDIS_PORT / REDIS_PASSWORD — must match the redis service requirepass
ACCESS_TOKEN_* / REFRESH_TOKEN_* / ENV_ENCRYPTION_KEY — rotate away from template values
CORS_ALLOWED_ORIGINS — comma-separated browser origins (include http://LAN-IP and https://hostname as needed)
FRONTEND_URL / BACKEND_URL / DEV_TOOL_URL / VITE_BACKEND_API — URLs browsers and peers can actually reach
AVAILABLE_PLUGINS_FOLDER / INSTALLED_PLUGINS_FOLDER / APP_DATA_FOLDER / PLUGINS_ENV_FILE — paths inside the backend container, backed by host volumes
BASE_VERSION + image tags — keep aligned with plugin @quan-erp/* versions
DB_SYNC — fine for early local/dev; use migrations for staging/production schema changes
MODE — template often uses dev; production deployments should use the intended production mode

7. Staging & production checklist

Treat the template compose file as a starting point, not a finished production config.

Run ./install.sh install on a clean Linux host before first start
Change all default passwords (Postgres, Redis, ROOT_ADMIN_*, DEVELOPER_CONFIG_PASSWORD) and token / encryption secrets
Do not publish Postgres or Redis ports publicly; terminate TLS on Nginx (or another reverse proxy)
Persist ./data, installed-plugins, available-plugins, and logs on durable volumes / backups
Disable unsafe defaults (example secrets, open CORS, DB_SYNC=true, weak mem_limit on production workloads) before go-live
Ship plugins via pack / available-plugins + UI install — do not SQL-seed modules on prod
Run TypeORM migrations for schema changes; do not rely on synchronize in production
Confirm FRONTEND_URL, BACKEND_URL, and VITE_BACKEND_API match the public hostnames (not a private LAN IP unless that is intentional)
Align base image tags and plugin @quan-erp/* versions before upgrading
Never commit real FIREBASE_CONFIG private keys, npm tokens, or production passwords into compose files checked into git

8. Day-2 operations

Start / stop stack: cd installation && ./install.sh start|stop
Update base: pull/build new base-backend / base-frontend tags → recreate containers
Update a plugin: quan-erp build:prod|pack:prod → place under available-plugins → install / upgrade in UI
Health: docker compose ps; check backend logs
Data: back up Postgres volume and APP_DATA_FOLDER regularly
Rollback: keep previous plugin version folders and image tags until the new release is verified

YAMLUseful compose commands

cd installation   # or cd base for the Node template
docker compose logs -f backend
docker compose restart backend frontend
docker compose down
./install.sh start

Troubleshooting

./install.sh install fails — unsupported OS, missing sudo, or Docker repo not reachable; install Docker manually if needed
docker: permission denied — log out/in after install so the docker group applies
start fails — ensure POSTGRES_* / REDIS_* and image tags exist in docker-compose.yaml
Backend cannot reach DB — DATABASE_HOST / DB_HOST must be db, DB_PORT=5432; not localhost
Frontend cannot call API — VITE_BACKEND_API must be a browser-reachable host (LAN IP / public URL), not only an in-compose hostname
Plugin missing in UI — not in available-plugins, wrong version folder, or module row missing (local only)
Installed but UI blank — frontend dist / module.js not copied; rebuild and reinstall
Auth / CORS failures — FRONTEND_URL and CORS_ALLOWED_ORIGINS must include the browser origin
Version errors after upgrade — base image tag and plugin @quan-erp/* packages out of sync

Need help with deployment?

If you run into trouble deploying Quark ERP, you can get support from The Paradance. Help may be free or billed as an additional charge depending on the case — scope, urgency, and environment.

Include BASE_VERSION / image tags, OS, compose logs, and steps to reproduce
Simple guidance may be free; hands-on setup, production hardening, or custom ops work may be charged
We confirm free vs paid before starting paid work

Support →Email The Paradance →