Quick Start — Node.js

Publish a working Node.js application on Zenifra using GitHub Repository source.

Prerequisites

Node.js 18+ installed locally
a GitHub account
access to the Zenifra console

Note: This quickstart covers only projects with GitHub Repository source.

Step 1 — Create your application

mkdir hello-zenifra
cd hello-zenifra
npm init -y
npm install express

Create index.js:

const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.json({ message: 'Hello from Zenifra!', time: new Date().toISOString() });
});

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server running on port ${PORT}`);
});

Update package.json with a start command:

{
  "scripts": {
    "start": "node index.js"
  }
}

Confirm that package-lock.json was generated and is synchronized with package.json before publishing the project. Commit both files to the application root directory.

Verify dependency installation with the same Node.js version that you will select on Zenifra:

npm ci
npm start

Step 2 — Publish to GitHub

Create a repository on GitHub and push the code:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/your-username/hello-zenifra.git
git push -u origin main

Step 3 — Create the project on Zenifra

In the console, choose GitHub Repository as the project source.
Select the repository and the main branch.
In the runtime field, select Node.js.
In the Port field, enter 3000.
In build, use npm run build if package.json has a build script; otherwise, leave the field empty.
In start, use npm start.
If you want automatic updates on push, enable auto-deploy during creation.
Click Create Project.

Step 4 — Validate the deployment

Open the URL at *.clients.zenifra.com. You will see:

{ "message": "Hello from Zenifra!", "time": "2026-04-30T14:00:00.000Z" }

Also test /health to confirm the application is ready.

If auto-deploy was enabled during creation, Zenifra will update the instance automatically on each push to main.

Troubleshooting

Problem	Solution
The application does not start	Check whether the value configured in the Port field matches the port your application actually listens on
URL does not respond	Confirm the application listens on `0.0.0.0`
Missing or invalid `package-lock.json`	Generate it with npm, commit it next to `package.json`, and verify with `npm ci`
Lockfile is out of sync	Run `npm install`, commit the updated `package-lock.json`, and run `npm ci` again
Project uses pnpm or Yarn	Review the current Node.js dependency requirements before adapting the project; `pre-build` runs only after the initial npm installation
Another build command failed	Review Build Logs and verify `npm run build`, when present, and `npm start` locally