Skip to content
zefıly

How to host a Node.js app on your own server

Zefily runs your Node.js app as a systemd service on a local port. The web server in front handles the domain, HTTPS and static files, and every deploy builds the app before it switches to the new release.

Before you start

  • A server connected to Zefily with the web stack installed.
  • A Node.js app in Git with package-lock.json committed.
  • A domain whose DNS points to the server.

Steps

  1. 1. Install Node.js

    In the server's web stack click Install Node.js and choose 22, 24 or 26. Pick the version your app was built and tested with.

  2. 2. Add the site

    Choose Sites, then Add site. Select Runs on: Node.js and the version, and enter the domain. Zefily assigns a free local port to the app.

  3. 3. Set up the Git deploy

    On the site's Deploy pane choose the Node.js preset and your repository. The build commands are npm ci and npm run build --if-present, and the start command is npm start.

  4. 4. Listen on the assigned address and port

    The app must listen on 127.0.0.1 and on the PORT the environment gives it, not on a fixed port. The environment also sets HOST=127.0.0.1 and NODE_ENV=production.

  5. 5. Commit the lock file

    Commit package-lock.json. Without it the preset runs npm install instead of npm ci, so versions can change between deploys. A release with only a yarn.lock or pnpm-lock.yaml also installs with npm for now.

  6. 6. Add the configuration

    Put settings and secrets in the site's .env, and connect a database to get DATABASE_URL. Keep .env out of Git.

  7. 7. Run background jobs as daemons

    Queue consumers, schedulers and bots run as daemons of the site user, with their working folder in the live current folder of the site.

  8. 8. Deploy and check

    Click Deploy now. The service restarts on the new release. If it does not answer after the deploy, the site switches back to the previous release by itself.

Verify it works

Open the domain: your app answers over HTTPS. The App process output on the Logs pane shows the service start, and a route you know returns the response you expect.

Troubleshooting

502 Bad Gateway after a deploy
The app does not listen on 127.0.0.1 and $PORT, or it exits at start. Read App process on the Logs pane; the site then rolls back on its own.
npm ci fails on the server
The lock file does not match package.json. Run npm install on your computer, commit the updated package-lock.json and deploy again.
The build needs a dev tool that is missing
Production installs skip devDependencies, so a build tool listed there is absent. Move the tool into dependencies.

Questions

Which Node.js versions can I install?

Node.js 22, 24 and 26 are available. Choose the one your app supports; you can install more than one for different sites.

Do I need pm2 or another process manager?

No. Zefily runs the app as a systemd service and restarts it on every deploy. WEB_CONCURRENCY tells the app how many worker processes the server can run.

Do Nuxt, SvelteKit, Astro or Express apps run here?

Yes. Any Node.js app that listens on 127.0.0.1 and the assigned port runs the same way, with the same deploy steps.

Read next

Start on a server you own

Create your account, connect a server and follow the guide. The server stays yours: you pay your provider.

Start free

Black Friday & Cyber Monday

Before you go: lifetime plans are on sale

Pay once for a lifetime plan, or get 30% off the first year of any yearly plan.

Only 100 lifetime plans per plan. When they are gone, they are gone.

See the campaign

Amazing November

See the campaign →