How to Deploy Luban H5 to Production: A Complete Guide

Deploy Luban H5 to production by installing Node.js and PM2, cloning the repository, running ./luban-h5.sh init to compile the Vue frontend and Strapi backend, then executing ./luban-h5.sh start to launch the managed service on port 1337.

Luban H5 is an open-source SaaS platform built on Node.js that powers a Vue-based visual editor with a Strapi CMS backend. Whether you are deploying to a CentOS server, Ubuntu VPS, or cloud instance, this guide covers the exact steps and configuration files needed for a stable production deployment.

Prerequisites and System Preparation

Before you deploy Luban H5 to production, install the required system packages and process managers. The project requires Node.js (v10 or higher), Yarn, PM2 for process management, and optionally Nginx for reverse proxying.

Install the core dependencies on CentOS:

curl --silent --location https://dl.yarnpkg.com/rpm/yarn.repo | sudo tee /etc/yum.repos.d/yarn.repo
sudo yum install -y nodejs npm yarn nginx
sudo npm install -g pm2

For users in mainland China, configure a fast npm mirror to avoid build failures. Run the provided mirror script at deploy/mirror.sh which rewrites registry URLs to use npmmirror.com:

./deploy/mirror.sh

This script modifies npm and Yarn configurations across lines 18-90 of the source file, ensuring reliable package installation during the build phase.

Building the Application

The deployment process separates the build stage from the runtime stage. You must compile both the frontend editor and the backend API before starting the service.

Frontend Build Process

The Vue-based editor resides in front-end/h5/. During initialization, the luban-h5.sh script (lines 92-100) executes yarn && yarn build within this directory to generate the editor bundle and preview engine assets.

Backend Build Process

The Strapi API is located in back-end/h5-api/. The build process sets NODE_ENV=production and compiles the admin UI:

cd luban-h5
./luban-h5.sh init

The init command performs three critical actions:

1. Installs frontend dependencies and builds the editor
2. Installs backend dependencies in back-end/h5-api/
3. Executes NODE_ENV=production yarn build to generate the Strapi admin panel

Starting Production Services

Once the build completes, start the application using the PM2 process manager. The luban-h5.sh start command (lines 103-106 of the source) spawns the Strapi server via server.js:

./luban-h5.sh start

The back-end/h5-api/server.js file (lines 9-11) contains the minimal bootstrap logic that initializes Strapi and begins listening on the configured port. By default, Luban H5 exposes port 1337.

Verify the deployment by accessing the endpoints:

• Frontend preview: http://<SERVER_IP>:1337/
• Admin panel: http://<SERVER_IP>:1337/admin

To ensure the service restarts after a system reboot, save the PM2 process list and enable the startup script:

pm2 save
pm2 startup

Configuring Nginx as a Reverse Proxy

For production environments, place Nginx in front of the Node.js application to handle TLS termination, static asset serving, and load balancing. A typical server block forwards traffic to port 1337 while serving the compiled Vue editor files directly:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:1337;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

This configuration improves performance by allowing Nginx to serve static assets from front-end/h5/dist/ while proxying API requests to the Strapi backend.

Troubleshooting Common Deployment Issues

Native module build failures: If you encounter sqlite3 or node-gyp errors during yarn install, ensure you ran ./deploy/mirror.sh to use the Alibaba Cloud mirror. Slow default registries often timeout during binary compilation.

Port 1337 inaccessible: Cloud provider security groups commonly block port 1337. Add an inbound rule for TCP 1337, or configure Strapi to listen on port 80/443 via environment variables in back-end/h5-api/.env.

PM2 process not found after reboot: Without pm2 save and pm2 startup, the Luban H5 service will not auto-restart. Execute these commands after the initial ./luban-h5.sh start to persist the process list.

Summary

• Install dependencies: Node.js, Yarn, PM2, and optionally Nginx on your production server.
• Use the mirror script: Run deploy/mirror.sh before building to avoid registry timeouts.
• Initialize the build: Execute ./luban-h5.sh init to compile both the Vue frontend (front-end/h5/) and Strapi backend (back-end/h5-api/).
• Start the service: Run ./luban-h5.sh start to launch the managed process via PM2 on port 1337.
• Persist the process: Use pm2 save and pm2 startup to ensure auto-restart after server reboots.

Frequently Asked Questions

What is the default port for Luban H5 in production?

By default, Luban H5 listens on port 1337. This is configured in the Strapi backend (back-end/h5-api/server.js). You must open this port in your firewall or configure a reverse proxy (Nginx) to forward traffic from port 80 or 443.

How do I build the Luban H5 frontend and backend separately?

While ./luban-h5.sh init builds both components, you can run them manually. For the frontend, execute yarn && yarn build inside front-end/h5/. For the backend, run yarn && NODE_ENV=production yarn build inside back-end/h5-api/.

Why does the deployment fail with sqlite3 or node-gyp errors?

These errors occur when native Node.js modules fail to download or compile, often due to slow npm registries in certain regions. Run ./deploy/mirror.sh before installing dependencies to switch to the npmmirror.com registry, which provides faster access to pre-built binaries.

How do I keep Luban H5 running after closing the terminal or rebooting?

The ./luban-h5.sh start command uses PM2 to daemonize the process. To ensure the service restarts automatically after a system reboot, run pm2 save to serialize the process list and pm2 startup to generate the system init script.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}