Node.js

The Node.js preset provides Node.js with npm, managed by a systemd service for automatic restarts and logging.

Available Versions

Version	Status
Node.js 22	LTS (default)
Node.js 24	LTS

Select a version when creating your pod. If not specified, Node.js 22 is used.

Node.js 18 and 20 are end-of-life and no longer get security fixes, so new pods can’t use them. Pods already on one keep running; switch them to 22 or 24 with the Node version picker below.

instapods pods create my-app -p nodejs --version 24

Switching Version Later

You aren’t locked into the version you picked. On the pod’s detail page, the Node version picker in the pod info panel switches an existing pod to any supported major in place - your files, environment variables, domain and plan all stay as they are.

Dashboard
API

Open the pod, choose a version next to Node version, and click Switch.

curl -X POST https://app.instapods.com/api/pods/my-app/node-version \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": "22"}'

The switch installs the new Node (moving down a major works the same as moving up), rebuilds native modules, and restarts every service on the pod that runs Node - your app, plus pm2 or any other Node worker you added. It runs in the background and usually takes under a minute, so the call returns straight away. The dashboard shows the result when it finishes, and it is also recorded on the pod’s Events tab. If a service that was running before the switch doesn’t start on the new version, the pod is put back on the version it had and the event names the service that failed, so a version your app can’t run on doesn’t leave it down. In the rare case that switching back fails too, the event says so and the pod stays on the new version. Only one switch runs on a pod at a time. Switching to the version the pod is already on reinstalls it and restarts its Node services; there is nothing to switch back to, so a service that fails to start is just named in the event. From the CLI, instapods pods node-version my-app 24 --wait does the same and waits for the result. It needs a CLI release newer than v1.16.0.

If your package.json declares an engines.node your pod doesn’t meet, you don’t need to do this by hand: Deploy Doctor spots it and offers the switch as a one-click fix.

What’s Included

Component	Version	Details
Node.js	22 or 24 (your choice)	JavaScript runtime
npm	Bundled with Node.js	Package manager
systemd	—	Process manager (`app` service)
git	Latest	Version control
SSH	OpenSSH	Access via dedicated port

Pre-installed utilities: curl, wget, vim, htop, unzip.

Directory Structure

/home/instapod/app/
├── package.json
├── index.js            # Entry point (configurable)
└── node_modules/       # (after npm install)

App Root: /home/instapod/app
App Port: 3000 (your app must listen on this port)
Environment: NODE_ENV=production is set by default

How the App Service Works

Your Node.js app runs as a systemd service called app. It:

Runs /usr/bin/node index.js from /home/instapod/app
Starts automatically on boot
Restarts on crash (on-failure policy)
Logs to the system journal (viewable via the Logs tab or CLI)
Runs as the instapod user

The service expects your app to listen on port 3000. The nginx proxy on the server forwards traffic from your pod’s public URL to this port.

Your app must bind to 0.0.0.0 (not localhost or 127.0.0.1) on port 3000, otherwise it won’t be reachable from the public URL.

Deploying Your App

Upload and Reload

# Sync your project
instapods files sync my-node-app --local ./my-project

# Reload (auto-installs deps + restarts)
instapods pods reload my-node-app

pods reload automatically runs npm install --production when it detects a package.json in your app directory. You don’t need to install dependencies manually.

Example Express App

// index.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello from InstaPods!');
});

app.listen(3000, '0.0.0.0', () => {
  console.log('Server running on port 3000');
});

{
  "name": "my-app",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^4.18.0"
  }
}

No Hot Reload

Node.js does not support hot reloading of code. Every code change requires a full process restart via pods reload. The restart takes about 1 second and causes a brief interruption.

Viewing Logs

instapods logs my-node-app -s app

Adding a Database

instapods services add my-node-app -s postgresql -w
instapods services creds my-node-app -s postgresql

Database services require the Build plan or higher.

Use Cases

Express / Fastify APIs
Next.js applications (standalone mode)
GraphQL servers
Real-time apps with WebSockets
Background workers and job queues

Getting Started

Dashboard

Presets

Services

SSH & Files

Guides

Partners

Support

Available Versions

Switching Version Later

What’s Included

Directory Structure

How the App Service Works

Deploying Your App

Upload and Reload

Example Express App

No Hot Reload

Viewing Logs

Adding a Database

Use Cases