Ecosystem File vs CLI-Only Management for Deploying a Stateful Node.js App Under PM2

Question

I'm deciding how to standardize PM2 deployments for a Node.js service that runs in cluster mode and holds some in-memory session state. The two documented approaches are starting processes directly with pm2 start app.js and persisting them with pm2 save plus pm2 startup, versus declaring everything in an ecosystem.config.js file under version control.

The CLI route is faster for prototyping, but I worry about configuration drift between staging and production when flags like -i max, watch settings, and environment variables live only in shell history. The ecosystem file makes cluster mode and per-environment variables declarative and reviewable, but adds a layer of indirection for quick local experiments.

There is also a behavioral tension I can't resolve from the docs alone: for a stateful app, pm2 reload promises zero-downtime staggered worker restarts in cluster mode, while pm2 restart hard-kills processes. It's unclear how in-flight connections are drained during a reload.

For a stateful cluster-mode app, does the ecosystem file offer any operational advantage over CLI flags beyond version control, or is it purely a maintainability choice?
Does pm2 reload wait for existing connections to close before replacing a worker, or must connection draining be handled in application code?
Given in-memory sessions, is cluster mode with reload safe, or should I assume a distributed session store is a hard prerequisite?

Tasadduq Burney · Answer

For a stateful Node.js application using cluster mode, the ecosystem.config.js file is more than a maintainability choice; it is an operational necessity. While CLI flags are useful for prototyping, they fail to provide the declarative state required to manage stateful lifecycles across environments.

1. Operational Advantages of Ecosystem Files
Beyond version control, the ecosystem file offers three critical operational advantages over CLI flags:

Declarative Cluster Configuration: Defining instances: 'max' or specific counts in a file ensures that the pm2 save command restores the exact topology after a server reboot. CLI flags are lost unless manually recorded in shell history.
  Environment Isolation: It allows for per-environment variables and watch settings to be managed in one code, preventing 'configuration drift' where staging might have different memory limits or restart policies than production.
  Auditability: The file serves as a source of truth for the process lifecycle, making it possible to review changes to resource limits or environment variables via pull requests.

2. Connection Draining: Reload vs. Restart
The behavioral tension between pm2 reload and pm2 restart is resolved by how PM2 handles signals:

pm2 reload: This performs a staggered restart. It sends a SIGINT to a worker, waits for it to exit, and then starts a new one. However, PM2 does not natively wait for in-flight connections to close. If your application code does not explicitly handle SIGINT to stop accepting new requests and finish processing existing ones before calling process.exit(), PM2 will eventually kill the process after the kill_timeout.
  pm2 restart: This is a hard-kill (SIGTERM/SIGKILL) of all workers simultaneously, dropping all in-flight connections immediately.

3. In-Memory Sessions and Cluster Mode
If your app holds in-memory state, cluster mode with reload is not safe without a distributed session store.

In cluster mode, each worker process has its own memory space. When pm2 reload replaces a worker, any session stored in that specific worker's memory is lost.
  Even with 'sticky sessions' at the load balancer level, a worker restart destroys the local data. For stateful apps to survive a reload or crash, a distributed store (like Redis or a database) is a hard prerequisite.

Diagnostic Question: Is your application currently using a local object to store sessions, or do you have an external data store like Redis configured?

Ecosystem File vs CLI-Only Management for Deploying a Stateful Node.js App Under PM2

1 answer

1. Operational Advantages of Ecosystem Files

2. Connection Draining: Reload vs. Restart

3. In-Memory Sessions and Cluster Mode

Your perspective belongs here.

0 question comments