PM2 Ecosystem Config Generator

What an ecosystem file is for

pm2 start dist/index.js --name api -i max works, but the flags live only in your shell history. An ecosystem file writes them down: the app's name, what to run, where, with which environment, how many instances and when to restart. It goes in the repository, so every server — and every person — starts the app the same way. Read more in What is PM2?

The options, and what they do

• script and args — what PM2 runs. For Next.js that is the next binary with start -p 3000; for a compiled NestJS app, dist/main.js; for anything started by npm start, the script is npm and the argument is start.
• cwd — the directory the app runs in. With release directories, point it at the current symlink so a reload picks up the new release.
• exec_mode: cluster and instances — run several copies of the app behind one port, one per CPU core with max. It helps CPU-bound apps on multi-core servers. The app must keep no state in memory between requests (sessions, caches), and npm scripts cannot run in cluster mode — point script at the Node entry file instead.
• max_memory_restart — restart the process when it grows past this size. A safety net for a slow leak, not a fix for one.
• exp_backoff_restart_delay — when the app crashes repeatedly, wait longer between restarts instead of restarting hundreds of times a minute and filling the logs.
• env — environment variables. They are set when the process starts; after changing them, use pm2 reload ecosystem.config.js --update-env or the old values stay.
• out_file, error_file and log_date_format — where logs go and whether each line is timestamped. By default they are in ~/.pm2/logs/.

Start it, and keep it running after a reboot

pm2 start ecosystem.config.js
pm2 save        # writes the current process list to ~/.pm2/dump.pm2
pm2 startup     # prints a command; run it once with sudo

pm2 startup installs a systemd unit that starts PM2 at boot, and PM2 then restores whatever was saved with pm2 save. Forgetting pm2 save is the most common reason an app is gone after a reboot.

Secrets in the ecosystem file

The file is usually committed, so keep real secrets out of it. Either leave them in a .env file on the server that the app loads itself (dotenv, or the --env-file flag in Node 20.6 and later), or generate the env block on the server at deploy time.

Logs that do not fill the disk

PM2 never rotates its own logs. Install the module once: pm2 install pm2-logrotate, then set a size and retention, for example pm2 set pm2-logrotate:max_size 10M and pm2 set pm2-logrotate:retain 14.

How Shipown runs your app under PM2

Shipown starts Node and Next.js apps under PM2 with the port, the health check and the restart policy set for you, reads PM2's state live, and can install and configure pm2-logrotate from the app. See deployments.