pm2-installer is designed to automate installation of pm2 as a service, particularly on Windows, even in environments without Internet access.
Unfortunately, PM2 has no built-in startup support for Windows. PM2's documentation recommends using either
pm2-windows-startup. However, both of these projects have some real drawbacks.
pm2-windows-startup adds an entry to the registry to start pm2 after user login. Because it does not create a service, PM2 will not be running until a user has logged into the user interface, and will halt when they log out. It has not been updated since 2015.
node-windows to create a service that runs pm2. This is a much better approach, but it hasn't been maintained since 2018, has outdated dependencies that cause crashes on setup, and currently fails to run properly on Node 14. It also runs the service as the the
Local System user instead of
This project creates its own Windows Service using the current version of
node-windows and a series of PowerShell scripts inspired by this excellent gist by @maxfierke & @mauron85.
When running on Windows,
npmto keep its global files in
C:\ProgramData\npm, instead of keeping them in the current user's
pm2globally, using an offline cache if necessary
- Create the
C:\ProgramData\pm2directory and set the
PM2_HOMEenvironmental variable at the machine level
- Set permissions both the new
pm2folders so that the Local Service user may access them
node-windowsto install a new Windows service
- Use PowerShell to configure the service to run as the Local Service user (due to node-windows#89)
- Confirm the service is running properly
- Install the
pm2-logrotatemodule so that log files don't fill up the disk
pm2 will be running in the background the
Local Service user. It will persist across reboots and continue running regardless of which user is logged in. To add your app, run
pm2 start app.js from an admin command line interface. Make sure to run
pm2 save to serialize the process list.
Download the latest version here.
Copy the entire
pm2-installer directory onto the target machine, then run:
npm run setup
On Windows, the
setup script assumes you have already configured
npm to use
cache directories in a location accessible to the
Local Service user. If not, it will issue a warning and ask if you're sure you'd like to proceed.
To set up
npm automatically, run
npm run configure npm run setup
npm installis not necessary, unless you're developing
pm2-installeritself and want to lint the project.
pm2-installer is also designed to function without an internet connection. It does this by creating a cache on an internet-connected build machine, then installing from that cache when run on the offline deployment machine.
On an internet-connected build machine running the same OS as the deployment target, run the following:
npm run bundle
This will populate the cache in the project's directory with the resources required to install offline. Transfer the entire
pm2-installer directory onto the deployment target, then run:
npm run setup
pm2-installer will check if it can contact the npm registry and install online if possible, or use the offline cache if not.
There are a couple additional challenges when installing on a fresh Windows machine. The
npm global directory is not accessible to other users by default, which means the
Local Service user will not be able to locate the
pm2 executable. Additionally, if the machine's PowerShell execution policy is
pm2 in PowerShell will fail- even though the setup script unblocks
pm2-installer includes two additional scripts to automatically fix the above issues. Invoking
npm run configure will create the
C:\ProgramData\npm\, and set
npm to use
cache locations in that directory. Running
npm run configure-policy checks the machine's PowerShell execution policy and if it is either
Restricted, updates it to
Open an elevated terminal (e.g. right click and select "Run as Admin") and run the following commands first:
npm run configure npm run configure-policy
npm run setup to install the pm2 service.
Additional context for Windows installations
pm2service runs as the
Local Serviceuser. To interact with
pm2, you need to use an elevated terminal (e.g. right click and select "Run as Admin") before running any commands that interface with the service, e.g.
- If you update node and npm, make sure to either manually re-configure your npm & node installations or run
npm run configureagain.
- This project does not currently support nvm for windows. It requires a standard node installation.
To remove the pm2 service, run:
npm run remove
This will remove the service and completely uninstall pm2.
If you used the
configure script on Windows to configure
npm, you can revert those settings by running:
npm run deconfigure
MIT © Jesse Youngblood