PM2 ecosystem.config.js example: run Node apps in the background

Run a Node.js app with PM2: restarts on crash, memory limit, cluster mode and start at boot.

For Node.js apps managed with PM2 on Linux, macOS or Windows.

PM2 keeps a Node.js app running, restarts it if it crashes, and can start it at boot. An ecosystem file keeps all its settings in one place. Fill in your app below and save the result in your project folder.

Create your config file

Type your own values. The file below updates as you type, and nothing you type leaves your browser.

module.exports = {
  apps: [
    {
      name: "myapp",
      script: "server.js",
      instances: 1,
      exec_mode: "fork",
      watch: false,
      autorestart: true,
      max_memory_restart: "300M",
      env: {
        NODE_ENV: "production",
        PORT: 3000,
      },
    },
  ],
};

How this setup works

Step-by-step setup

1. Install PM2: npm install -g pm2.
2. Save the file as ecosystem.config.js in your project folder.
3. Start the app: pm2 start ecosystem.config.js.
4. Check it: pm2 status and pm2 logs myapp.
5. Start it at boot: run pm2 startup, run the command it prints, then pm2 save.

What the important lines mean

• script is the file PM2 runs: server.js.
• exec_mode is fork. Cluster mode runs several copies that share the port.
• env sets NODE_ENV and PORT for the app. Your app must read PORT.

Common errors and how to fix them

Script not found

The path is wrong or relative to a different folder. Use a full path or set the working folder.

The app is stuck in an errored state

Run pm2 logs myapp to see the error. Often a missing module or a port already in use.

The app is gone after a reboot

Run pm2 startup, then the command it prints, then pm2 save.

Cluster mode does not start

Cluster mode suits servers that listen on a port. For scripts and workers, use fork mode.

Frequently asked questions

What is the difference between fork and cluster mode?

Fork runs one copy. Cluster runs several copies of a web server that share one port, using all CPU cores.

How do I reload the app without downtime?

In cluster mode, run pm2 reload with the app name.

Where do the logs go?

PM2 keeps them in ~/.pm2/logs. Use pm2 logs to read them.

Written for: PM2 5.4, Node 20 · Updated 2026-10-03

Free tools that help

• Common ports listSearch a list of common TCP and UDP port numbers: SSH 22, HTTP 80, HTTPS 443, MySQL 3306, PostgreSQL 5432 and more, with dev server ports.

Fix a problem with this setup

• Node EADDRINUSEFix EADDRINUSE in Node, Express, Next.js and Vite: find the program using the port, stop it, or start on another port.
• Port already in useFind which program holds a port on Windows, macOS or Linux, then stop it or use another port.

More server configs

• WireGuard server config (wg0.conf)Set up a WireGuard VPN server on Linux with one peer, NAT and the right commands.
• WireGuard client configCreate the client file that connects to your WireGuard server, with DNS, allowed IPs and keepalive.
• nginx HTTPS server blockServe your site over HTTPS with nginx: certificate paths, HTTP to HTTPS redirect, HSTS and a proxy or static site.
• .htaccess fileBuild an Apache .htaccess file with an HTTPS redirect, www rules, compression, caching and a front controller.
• robots.txt fileCreate a robots.txt that tells search engines what to crawl, with a sitemap line and optional AI crawler blocks.
• nginx redirect www to non-wwwSend www.example.com to example.com (or the reverse) with one permanent redirect.

See all 41 config generators