theborch / pm2-cookbook

Chef cookbook to install and manage PM2.

PM2 Cookbook

Chef coookbook to install and manage PM2.

Requirements

Depends on the cookbooks:

• nodejs

Platforms

• Centos 6+
• Amazon Linux
• Ubuntu 14+
• Debian 7+

Attributes

default.rb

Attribute	Type	Description	Options	Default
['pm2']['version']	String	PM2 node module version to install	-	latest

Up the chain

The nodejs cookbook uses the following attributes to define the nodejs and npm formats to install - override them for the desired behaviour.

Attribute	Description
['nodejs']['install_method']	Nodejs install method
['nodejs']['npm]['install_method']	NPM install method

See the nodejs cookbook for details.

Recipes

default.rb

Installs PM2 as a global node module using a specific version if specified in the default attributes described above.

nodejs.rb

Install nodejs and npm using the nodejs cookbook.

Example

To install PM2:

Add the pm2 cookbook as a dependency:

depends 'pm2'

Include the pm2::default recipe:

include_recipe 'pm2::default'

Providers

pm2_application

The pm2_application provider manages a json configuration file for a node application and controls it with PM2.

It only start processes from a json configuration (located in /etc/pm2/conf.d) and it does not support starting processes by calling the PM2 CLI directly.

Actions

The available actions try to represent some of the PM2 CLI control actions.

Action	Description	Notes
:deploy	Create a json configuration file for a node application	All configuration files are deployed in /etc/pm2/conf.d
:start	Start an application defined as a json file	It does not change the state of a running application - use one of the start_or_restart/start_or_reload methods instead
:stop	Stop an application	Invokes the PM2 CLI to stop an application by name
:stop	Restart an application	Invokes the PM2 CLI to restart an application by name only if it is running
:reload	Reload an application	Invokes the PM2 CLI to reload an application by name only if it is running
:graceful_reload	Gracefully reload an application	Invokes the PM2 CLI to gracefully reload an application by name only if it is running
:start_or_restart	Start or restart an application	Invokes the PM2 CLI to start or restart an application by name
:start_or_reload	Start or reload an application	Invokes the PM2 CLI to start or reload an application by name
:start_or_graceful_reload	Start or gracefully reload an application	Invokes the PM2 CLI to start or gracefully reload an application by name
:delete	Stop and delete an application json file	Invokes the PM2 CLI to stop an application and deletes the json file from the filesystem
:startup	Configures PM2 to start on boot	Invokes the PM2 CLI to configure the startup process for the running platform

If no action is specified then the default action [:deploy, :start_or_restart, :startup] will be used.

Attributes

The available attributes try to represent the PM2 json definition options schema.

Attribute	Type	Description	Required
name	String	Name of the application - See PM2 documentation for reference - Note: this is the resource name attribute	Yes
script	String	Node script to execute - See PM2 documentation for reference	Yes
user	String	User to execute the node process - defaults to `root`	No
home	String	Value of the PM2_HOME environmental variable - Note: a .pm2 directory will be appended to the PM2_HOME value if missing	No
args	Array	See PM2 documentation for reference	No
node_args	Array	See PM2 documentation for reference	No
max_memory_restart	String	See PM2 documentation for reference	No
instances	Integer	See PM2 documentation for reference	No
log_file	String	See PM2 documentation for reference	No
error_file	String	See PM2 documentation for reference	No
out_file	String	See PM2 documentation for reference	No
pid_file	String	See PM2 documentation for reference	No
cron_restart	String	See PM2 documentation for reference	No
cwd	String	Location of the node script to execute - See PM2 documentation for reference	Yes
merge_logs	TrueClass/FalseClass	See PM2 documentation for reference	No
ignore_watch	Array	See PM2 documentation for reference	No
watch_options	Hash	See PM2 documentation for reference	No
env	Hash	See PM2 documentation for reference	No
log_data_format	String	See PM2 documentation for reference	No
min_uptime	String	See PM2 documentation for reference	No
max_restart	Integer	See PM2 documentation for reference	No
exec_mode	String	See PM2 documentation for reference	No
exec_interpreter	String	See PM2 documentation for reference	No
write	TrueClass/FalseClass	See PM2 documentation for reference	No
force	TrueClass/FalseClass	See PM2 documentation for reference	No

Example

To deploy and start (or restart) a test.js application that lives in /tmp/test.js:

Install PM2 as described in the Recipes example above.

Use the pm2_application provider - most basic example:

pm2_application 'test' do
  script 'test.js'
  cwd '/tmp'
  action [:deploy, :start_or_restart]
end

This will deploy a /etc/pm2/conf.d/test.json configuration file and start/restart the application with PM2.

References

• PM2 advanced documentation

Development / Contributing

Dependencies

• Ruby
• Bundler

Installation

$ git clone [e-mail]:Mindera/pm2-cookbook.git
$ cd pm2-cookbook
$ bundle install

Tests

To run unit tests (chefspec):

$ bundle exec rake unit

To run lint tests (rubocop, foodcritic):

$ bundle exec rake lint

To run integration tests (kitchen-ci, serverspec):

$ bundle exec rake integration