PieHost

NodeJS Deployment

PieApp supports deploying Node.js backend applications directly from a Git repository. Your app runs as a long-lived process inside a Docker container, with incoming traffic routed to the port it listens on.

PieApp detects a Node.js app by inspecting package.json dependencies for known frameworks. If no frontend framework is matched, the app defaults to Node.js.

Supported Frameworks 

Framework Detected subtype
Express express
Fastify fastify
NestJS nestjs
Koa koa
Generic Node.js node

To override auto-detection, add a pie.json to your repo root:

{
  "type": "nodejs",
  "subtype": "express"
}

Requirements 

  • A Git repository with package.json at the root
  • A server that binds to a configurable port

Getting Started 

1. Go to the PieApp dashboard, click Launch and select PieApp.

2. Set the Node Entry File and Node Port in the Settings tab (see Entry File & Port below).

3. Set your Build Commands if your app requires a build step (e.g. TypeScript compilation).

4. Add environment variables in the Environment tab.

5. Click Deploy. PieApp installs dependencies, runs your build commands, and starts your app with:

node /app/<entry-file> --port <node-port>

Your app will be live at https://yourapp.pie.host once the deployment status shows Deployed.

Entry File & Port 

Node Entry File

The Node Entry File is the file PieApp uses to start your application, relative to the repo root. Set this in the Settings tab.

App type Typical entry file
Express / Koa / Fastify server.js or index.js
NestJS (compiled) dist/main.js
Generic app.js

Node Port

The Node Port is the port your application listens on inside the container. Set this in the Settings tab and make sure your app actually binds to this port.

PieApp passes it as a --port flag when starting your process:

node /app/server.js --port 3000

Read it in your app like this:

const args = process.argv;
const portIndex = args.indexOf('--port');
const PORT = portIndex !== -1 ? parseInt(args[portIndex + 1]) : 3000;

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Or using a package like minimist:

const argv = require('minimist')(process.argv.slice(2));
const PORT = argv.port || 3000;

If your app does not listen on the configured port, PieApp's health check will fail and the deployment will not go live.

Node Version 

Set the Node Version in the Settings tab (e.g. 18, 20, 22). If left blank, the default system Node.js version is used.

Changing the Node version triggers a cold deployment — the entire image is rebuilt from scratch.

Build Commands 

Set these in the Settings tab under Build Commands.

For a plain JavaScript app, no build step is needed. For TypeScript or apps that require compilation:

NestJS

npm install && npm run build

TypeScript (tsc)

npm install && npx tsc

Generic

npm install && npm run build

npm install must be included in Build Commands so dependencies are available at runtime.

Environment Variables 

Add your configuration in the Environment tab, one per line in KEY=VALUE format:

NODE_ENV=production
DATABASE_URL=postgres://user:password@host:5432/dbname
JWT_SECRET=your_secret_here
REDIS_URL=redis://your-redis-host:6379

Variables are available via process.env.KEY at runtime.

Do not hardcode secrets in your source code. Always use environment variables for credentials and API keys.

Cron Jobs 

Add scheduled tasks via a pie.json file in the root of your repository:

{
  "crons": [
    {
      "schedule": "0 * * * *",
      "command": "/usr/bin/node /app/scripts/cleanup.js"
    }
  ]
}

All repository files are available under /app/ inside the container. Changes to pie.json take effect after the next deployment.

Common Issues 

App deployed but returning 502 Bad Gateway

Your app is not listening on the port configured in the Node Port setting. Ensure your server binds to the port passed via the --port flag.

Cannot find module error during startup

npm install was not run or failed. Make sure your Build Commands include npm install.

App works locally but crashes on PieApp

Check that all environment variables your app depends on are set in the Environment tab. A missing DATABASE_URL, JWT_SECRET, or similar will cause a crash at startup.

TypeScript / compiled app not found

If your entry file is dist/main.js but the dist/ folder is not being created, ensure your Build Commands include the compilation step (e.g. npx tsc or npm run build) and that tsconfig.json outputs to the expected directory.

Help

Facing difficulties? Use the chat box on the bottom-right corner of this page to reach us.