Node.js apps

Deploy Next.js, Nuxt, NestJS, Express and other Node.js servers with the right Node version, PORT, persistent files, cluster mode, rollback and logs.

Updated Oct 9, 2026 · 8 min read

ZoPanel runs a Node.js server as a systemd service of the hosting account, behind nginx, which handles the domain, SSL and request limits. Use this page when your project has a package.json and runs a server process. For front-end builds that produce only static files (Vite, Create React App, Angular, Next.js static export), see Static sites. For the general deployment pipeline shared by all languages, see Git deploy.

Prerequisites

• At least one Node.js version installed on the server (the installer adds Node.js 22 by default).
• A website of type Git deploy, or any website with its Deploy tab (for example Node / Proxy).
• The account's package must include Git deploy & apps. Otherwise the panel answers "this feature is not included in your hosting package".

Install Node.js versions (administrator)

1. Open Runtimes in the admin menu.
2. Under Other runtimes, find the Node.js card.
3. Click Node 24, Node 22, Node 20 or Node 18. Several versions can be installed side by side.

ZoPanel downloads the latest release of that major version from nodejs.org, verifies its SHA-256 checksum, installs it in /opt/zopanel/runtimes/node/<major> and adds pnpm and yarn. Installed versions can be removed from the same card.

Note: Node.js 18 and 20 have reached end of life in the official Node.js release schedule. Use 22 or 24 for new projects.

Which version an app uses

If the requested major version is not installed, the newest installed version is used. You can also pin a version yourself: turn Auto-detect off in the Build & run card and pick it under Version (Latest installed = the newest one).

Tip: engines.node: ">=18" selects Node.js 18 when it is installed. Write the major you actually want in .nvmrc.

Detection

On every deploy, unless Auto-detect is off, ZoPanel reads package.json and fills in the build settings. A project with composer.json is treated as PHP unless it depends on a Node server framework. Likewise, a Python web app (with manage.py, or django, flask, fastapi, uvicorn or gunicorn in its Python dependency files) is treated as Python when package.json has neither a start script nor a Node server framework; see Python apps.

Package manager: pnpm-lock.yaml (or "packageManager": "pnpm@…") → pnpm install --frozen-lockfile; yarn.lock (or yarn@…) → yarn install --frozen-lockfile; package-lock.json or npm-shrinkwrap.json → npm ci; otherwise npm install. A bun lockfile is installed with npm install. The build command is <pm> run build when a build script exists.

Next.js with output: 'export', Astro without @astrojs/node, SvelteKit with adapter-static, and Vite projects without a start script are deployed as static sites. A Procfile with a web: line always provides the start command.

Click Analyze repository on the Deploy tab to see the result before deploying, then Use these settings and customize to edit it. Notes such as "Could not find a start script; set the start command manually" appear under the settings.

Deploy an app

1. Open Websites → New website, choose Git deploy, enter the Repository URL, Branch and, for monorepos, the Root directory, then click Create website.
2. Wait for the first deployment in the task log. ZoPanel clones the code, runs the install and build commands, starts the app and switches traffic to it once it is healthy.
3. To change commands, open the Deploy tab, turn Auto-detect off in Build & run, edit the fields and click Save & deploy.

To deploy without Git, choose Uploaded files (File Manager) under Source, upload the project to domains/<domain>/source and click Deploy.

PORT and HOST

The app must listen on 127.0.0.1 at the port in the PORT environment variable. ZoPanel sets PORT (different for each blue/green slot) and HOST=127.0.0.1; you cannot override them.

// Express
const port = process.env.PORT || 3000;
app.listen(port, "127.0.0.1");

// NestJS: main.ts
await app.listen(process.env.PORT ?? 3000, "127.0.0.1");

next start, Nuxt's server output, SvelteKit's adapter-node and Astro's @astrojs/node read PORT on their own. Never hard-code a port.

Environment variables

Add variables in the Environment variables card, or click Paste .env to paste many at once. Then click Save & redeploy.

• Up to 200 variables. Names use letters, digits and _ and cannot start with a digit; values are a single line of up to 8,192 characters.
• Variables are available to the install and build commands and at runtime. Members with view-only access see the names, not the values.
• NODE_ENV=production is set for the running app only. During the build it is not set, so npm ci still installs devDependencies (TypeScript, Vite…). Important: if you add NODE_ENV=production yourself, it also applies to the build and npm skips devDependencies, which usually breaks the build.
• CI=true is set during the build.

Persistent paths

Each deployment builds into a new folder under domains/<domain>/releases/, so files the app writes there disappear with the next release. List folders or files to keep in Persistent paths, separated by commas, for example uploads, .env.

• They are stored in domains/<domain>/shared/ and linked into every release. On the first deploy, content already in the repository at that path is copied there.
• Names starting with .env are treated as files, everything else as folders.
• Important: when .env is a persistent path and the website has environment variables, ZoPanel rewrites shared/.env from those variables on every deploy. Keep values in one place.

Cluster mode (every CPU core)

A Node.js process uses one CPU core. The Use every CPU core card (Node.js server apps only) starts one worker per CPU the package allows, up to 16, without code changes: ZoPanel preloads a small helper with Node's cluster module, and the workers share the port.

1. Make sure the app keeps no state in memory: sessions, caches, rate-limit counters and websocket rooms must live in Redis or a database.
2. Turn on One process per CPU core (redeploys to apply). Changing the switch starts a deployment.

A crashed worker is restarted after one second; after more than 20 quick crashes the app stops with [zopanel] workers keep crashing, stopping in the output. To use fewer workers, set ZP_CLUSTER_WORKERS in the environment variables.

Zero-downtime deploys and rollback

Every server app has two slots. A new release starts in the idle slot on its own port and must answer the Health check path (default /) with an HTTP status below 500 within 90 seconds. Only then does nginx switch to it; the previous process is stopped a few seconds later, so requests in flight finish. A release that fails to build, exits or never becomes healthy is discarded and the live one keeps running.

The Releases card keeps the last 5 builds. Rollback starts the chosen release in the idle slot with the current settings and switches after the health check, without downtime. It does not rebuild.

Note: during a switch both releases run at the same time for a few seconds, which also doubles memory use for that moment.

Logs

• Application output on the Deploy tab shows the last 400 lines of stdout and stderr from both slots. Turn on Live to follow it.
• The build log of each deployment is in Tasks, or click View log in Deployments.
• The website's Logs tab shows nginx's access and error logs.

Memory and CPU limits

The app runs inside the hosting account's resource group, so the package's RAM, CPU and process limits apply to all its websites together. The status card shows the app's current RAM. If the account runs out of memory, the kernel stops the process and systemd restarts it after one second.

To give V8 a heap limit below the package's memory, add an environment variable:

NODE_OPTIONS=--max-old-space-size=384

WebSockets

nginx forwards the Upgrade and Connection headers, so WebSockets and Server-Sent Events work without extra settings. Proxy buffering is off and a connection idle for 300 seconds is closed, so send a ping or heartbeat more often than that. With cluster mode on, use a shared adapter (for example Socket.IO's Redis adapter) and the WebSocket transport, because each worker holds its own connections.

Troubleshooting

Related

• Git deploy
• Node.js and Python apps
• Static sites and front-end builds
• Packages and limits
• Next.js deployment docs
• Node.js release schedule