# How to Deploy Luban H5 to Production: A Complete Guide

> Easily deploy Luban H5 to production. Follow our guide to install Node.js PM2, clone the repo, compile Vue and Strapi, and start the service on port 1337.

- Repository: [小小鲁班/luban-h5](https://github.com/ly525/luban-h5)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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:

```bash
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`](https://github.com/ly525/luban-h5/blob/main/deploy/mirror.sh) which rewrites registry URLs to use npmmirror.com:

```bash
./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`](https://github.com/ly525/luban-h5/blob/main/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:

```bash
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`](https://github.com/ly525/luban-h5/blob/main/server.js):

```bash
./luban-h5.sh start

```

The [`back-end/h5-api/server.js`](https://github.com/ly525/luban-h5/blob/main/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:

```bash
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:

```nginx
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`](https://github.com/ly525/luban-h5/blob/main/./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`](https://github.com/ly525/luban-h5/blob/main/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`](https://github.com/ly525/luban-h5/blob/main/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`](https://github.com/ly525/luban-h5/blob/main/./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.