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. 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. 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. 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. 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. 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. 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. 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. 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.