Running a Node.js app

A domain can run a Node.js server instead of publishing files. Hostctl builds it from a Git repository, starts it as the site's own user, and sends the domain's visitors to it.

What you need

• A plan that includes Node.js apps. If the Node.js app box says "This account can't run Node.js apps", ask your host.
• Node.js installed on the server. If the box says it isn't, ask your host.
• The repository connected on the domain's Git & apps tab (see Deploying a site from GitHub or GitLab).

Setting up the app

On the Git & apps tab, in the Node.js app box:

1. Choose Run as a Node.js app.
2. Pick the Node.js version: one of the installed LTS lines (22, 24 or 26). Builds use the same version.
3. Under Serves, choose the domain or one of its subdomains. Add a subdomain on the Subdomains tab first if you need one.
4. Set the Start command, one line run in the app's folder. The default is npm start.
5. Set the Health check path, / by default.
6. Press Save, then Deploy now.

The repository is copied as built, so install its dependencies with a build command such as npm ci (and npm run build if it needs one) in the Git settings.

Until the first deploy succeeds, the domain keeps serving its files.

Your app must listen on the port in $PORT, at the address in $HOST (127.0.0.1). Visitors reach it through the web server; nothing else can connect to that port from outside.

How a deploy starts the app

Each deploy builds the repository, starts the new version, and requests the Health check path. The app must answer with any status below 500 within 60 seconds. If it doesn't, the previous version starts again, and the deploy fails with "The app didn't answer after starting, so the previous release is running again". The deploy's log ends with the app's own last lines of output.

To roll back, press Redeploy on an earlier successful deploy. Hostctl builds that commit again as a new version.

Environment variables

Under Environment variables, type a NAME and value, then press Save variables. Saving restarts the app.

• Names use capital letters, digits and _, and can't start with a digit.
• Values are one line, up to 4 KB.
• Saved values are never shown again. Type a new value to replace one, or tick Remove.
• PORT, HOST, NODE_ENV, PATH, HOME and HOSTCTL_SHARED are set by Hostctl. NODE_ENV is production.

Where the app can write

The app's code is read-only while it runs. Write uploads, caches and other files to the folder in $HOSTCTL_SHARED, which stays the same from one deploy to the next.

The app can reach the internet, and MySQL or PostgreSQL on this server through 127.0.0.1 or their sockets.

Memory and restarts

Each app gets one CPU and the memory its plan allows, between 256 MB and 2 GB. An app that goes over its memory is stopped by the system and counts as a crash.

If the app crashes, it's restarted after two seconds. After five restarts within a minute it's left stopped, and the box shows Crashed. Fix the cause, then press Start.

Checking on the app

The box shows the app's state: Running (with its memory use, start time and restarts), Starting, Crashed, Stopped or Not deployed yet.

• Start, Restart and Stop control it. While it's stopped, visitors get an error.
• Show log shows the last 200 lines of the app's output. Refresh log loads them again.

Going back to publishing files

Choose Publish files (static or PHP) and press Save. The app stops and the domain serves its files again. Disconnect repository stops it too. The app's own folder stays on the server until you delete it.