jolly-roger / pm2-windows-service

Easily install (and uninstall) PM2 as a Windows service

pm2-windows-service

Allows easily installing and uninstalling PM2 as a service on Windows machines - inspired by pm2-windows-startup, and largely achieved using node-windows.

npm i pm2-windows-service -g

Install and Uninstall the Service

TIP: Run these from an administrative command prompt to avoid getting hit with a bunch of UAC dialogs

pm2-service-install

pm2-service-uninstall

Quickstart

After reading the caveats section, use PM2 to start the set of processes that you want the service to restore, and then just do:

pm2 save

The service will then restart that set of processes when the service is next started (by default this will be on system boot).

Configuration

You can control what the PM2 service runs using the PM2_SERVICE_SCRIPTS environment variable, which should be set to a semi-colon separated list of javascript files and/or json config files to run when the service starts (using pm2 start).

If PM2_SERVICE_SCRIPTS is not set, then the default behaviour is to call pm2 resurrect on service startup - when PM2 is running with the list of processes you want launched by the service, use pm2 save to dump the process list, ready for the service to restore it when it next starts.

Caveats

While testing this, a few caveats have arisen which need to be detailed upfront, as they can lead to issues when PM2 is installed as a service:

• If you run the service under one user account, and then attempt to interact with PM2 from the command line using a different account, you'll find things don't work as expected if the PM2_HOME environment variable contains any "user context" env vars (%APPDATA%, %USERPROFILE% etc.), or if one of the users cannot access the location of PM2_HOME.
  • To avoid this problem, either set PM2_HOME to an absolute path that all potential users (service and CLI) can write to, or run the service under the same account as you intend to use the CLI from.
• It also seems PM2 throws an error when you try to use the CLI from a non-administrative command prompt after it has been launched as a service, regardless of which user the service runs under (not tested with a non-admin user, yet).
  • Currently, the workaround for this, unfortunately, is just use an administrative command prompt if you need to access PM2 via command line when it is running as a service.
• Lastly, when launching json config files using PM2_SERVICE_SCRIPTS, problems arise if the apps declared in the config file don't explicitly have a cwd set (it ends up being the home dir of the service user).
  • pm2-windows-service attempts to solve this issue for you by automatically defaulting the cwd property to the directory of the config file when it isn't explicitly set, if this is an issue for you then explicitly setting the cwd for your apps might be what you need to do.

Logs

The service created by node-windows is currently placed in <global npm packages directory>/node_modules/pm2-windows-service/src/daemon/, as such, this is also where you will find the log output from the service, should you need it.