mindera/pm2-cookbook

Chef cookbook to install and manage PM2.

PM2 Cookbook

Chef coookbook to install and manage PM2.

Requirements

Depends on the cookbooks:

• poise-javascript

Platforms

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

Attributes

default.rb

Attribute	Type	Description	Default
['pm2']['node_version']	String	Node version to install	4.5.0
['pm2']['pm2_version']	String	PM2 node module version to install	latest
['pm2']['npm_version']	String	NPM node module version to install	latest

Recipes

default.rb

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

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
:restart	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 [email protected]:Mindera/pm2-cookbook.git
$ cd pm2-cookbook
$ bundle install

Tests

To run lint tests (rubocop, foodcritic):

$ bundle exec rake lint

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

$ bundle exec rake integration

pm2-cookbook's Issues

:startup generates dump file as root instead of using user if provided in version 0.7.1+

The following was added to providers/application.rb in commit 354060c

The following was added:

Save running processes

cmd = 'pm2 save'
execute cmd do
environment pm2_environment
command cmd
end

This block either needs to specify the user (if provided) or use the built-in pm2_command like this:

Save running processes

pm2_command('save')

Otherwise the file is executed as the current user (typically root) and causes permission errors when trying to run as the correct user.

Question: Installing without nodejs dependency

I was wondering if there was a way to use this cookbook without the nodejs dependency. I'm using the nvm cookbook to install node and would like to install pm2 for the version of node I designated there. Any ideas?

:delete doesn't actually pm2 delete the application

Up to version 0.7.3, the :delete action in providers/application.rb neglects to remove the running application from memory. This causes future pm2 save/dump commands to write this to the dump file and then pm2 resurrect brings it back despite it being removed from the /etc/pm2/conf.d directory.

Need to add a pm2_command('delete') if pm2_app_online? after deleting the config file.

Alternatively, since pm2 delete stops it, you could replace the stop command with delete.

Fix documentation at supermarket.

Documentation is ugly at supermarket, showing tags instead of the actual table: https://supermarket.chef.io/cookbooks/pm2

Problem installing after initial install

I'm having some trouble getting the pm2 chef install to work. It's been working fine, but seems to have just stopped. I've put the error below and the different attributes I've tried.

Have been able to replicate using test kitchen, and it seems to happen after the original "chef" of the image/box.

Any help would be much appreciated!

Try 1 Attributes

default['pm2']['node_version'] = '6.5.0'

Try 2 Attributes

default['pm2']['node_version'] = '6.5.0'
default['pm2']['npm_version'] = '4.1.1'

Try 3 Attributes

default['pm2']['node_version'] = '6.5.0'
default['pm2']['npm_version'] = '4.1.2'

Recipe: pm2::default
  * javascript_runtime[node] action install
    * poise_languages_static[/opt/nodejs-6.5.0] action install
      * poise_archive[/var/chef/cache/node-v6.5.0-linux-x64.tar.gz] action nothing (skipped due to action :nothing)
      * remote_file[/var/chef/cache/node-v6.5.0-linux-x64.tar.gz] action create (up to date)
      * directory[/opt/nodejs-6.5.0] action create (up to date)
       (up to date)
     (up to date)
  * node_package[pm2] action install

    ================================================================================
    Error executing action `install` on resource 'node_package[pm2]'
    ================================================================================

    Mixlib::ShellOut::ShellCommandFailed
    ------------------------------------
    Expected process to exit with [0], but received '1'
    ---- Begin output of ["/opt/nodejs-6.5.0/bin/node", "/opt/nodejs-6.5.0/bin/npm", "outdated", "--json", "--global"] ----
    STDOUT: {
      "npm": {
        "current": "4.1.1",
        "wanted": "4.1.2",
        "latest": "4.1.2",
        "location": "/opt/nodejs-6.5.0/lib/node_modules/npm"
      }
    }
    STDERR:
    ---- End output of ["/opt/nodejs-6.5.0/bin/node", "/opt/nodejs-6.5.0/bin/npm", "outdated", "--json", "--global"] ----
    Ran ["/opt/nodejs-6.5.0/bin/node", "/opt/nodejs-6.5.0/bin/npm", "outdated", "--json", "--global"] returned 1

    Cookbook Trace:
    ---------------
    /var/chef/cache/cookbooks/poise-languages/files/halite_gem/poise_languages/command/mixin.rb:207:in `tap'
    /var/chef/cache/cookbooks/poise-languages/files/halite_gem/poise_languages/command/mixin.rb:207:in `language_command_shell_out!'
    /var/chef/cache/cookbooks/poise-languages/files/halite_gem/poise_languages/command/mixin.rb:222:in `block in language_command_mixin'
    /var/chef/cache/cookbooks/poise-javascript/files/halite_gem/poise_javascript/resources/node_package.rb:213:in `npm_shell_out!'
    /var/chef/cache/cookbooks/poise-javascript/files/halite_gem/poise_javascript/resources/node_package.rb:128:in `check_package_versions'
    /var/chef/cache/cookbooks/poise-javascript/files/halite_gem/poise_javascript/resources/node_package.rb:106:in `load_current_resource'
    /var/chef/cache/cookbooks/compat_resource/files/lib/chef_compat/monkeypatches/chef/runner.rb:78:in `run_action'
    /var/chef/cache/cookbooks/compat_resource/files/lib/chef_compat/monkeypatches/chef/runner.rb:106:in `block (2 levels) in converge'
    /var/chef/cache/cookbooks/compat_resource/files/lib/chef_compat/monkeypatches/chef/runner.rb:106:in `each'
    /var/chef/cache/cookbooks/compat_resource/files/lib/chef_compat/monkeypatches/chef/runner.rb:106:in `block in converge'
    /var/chef/cache/cookbooks/compat_resource/files/lib/chef_compat/monkeypatches/chef/runner.rb:105:in `converge'

    Resource Declaration:
    ---------------------
    # In /var/chef/cache/cookbooks/pm2/recipes/default.rb

     18:   node_package pkg do
     19:     version node['pm2']["#{pkg}_version"] unless node['pm2']["#{pkg}_version"].nil?
     20:   end
     21: end

    Compiled Resource:
    ------------------
    # Declared in /var/chef/cache/cookbooks/pm2/recipes/default.rb:18:in `block in from_file'

    node_package("pm2") do
      package_name "pm2"
      action [:install]
      retries 0
      retry_delay 2
      default_guard_interpreter :default
      declared_type :node_package
      cookbook_name "pm2"
      recipe_name "default"
      version "latest"
      parent_javascript javascript_runtime[node]
      npm_binary "/opt/nodejs-6.5.0/bin/npm"
      timeout 900
    end

    Platform:
    ---------
    x86_64-linux

Berksfile.lock

Is there a particular reason your including the Berksfile.lock in this cookbook? Usually the lock file is not checked in to library cookbooks.

Invalid option "log_data_format" instead of "log_date_format"

https://github.com/Mindera/pm2-cookbook/blob/master/resources/application.rb#L47
Please find the detail about log_date_format here,
http://pm2.keymetrics.io/docs/usage/log-management

Support for modifying the runas user

Its generally not a good practice to run applications as a privileged user so there should be a user option that allows pm2 to be run as that user.

Change dependency to use https://github.com/poise/application_javascript

Right now pm2 cookbook uses https://github.com/redguide/nodejs/ as a dependency.

For later versions of node and chef, this doesn't work out that well. Can the dependency be https://github.com/poise/application_javascript instead? Even Amazon is using that as the boilerplate for chef 12 and nodejs:

https://github.com/awslabs/opsworks-linux-demo-cookbook-nodejs

Startup persistence is broken on the latest PM2 versions

I think this is related with a change on how the init script works introduced in the 1.0.2 release with:

[#1035 #1055] Deactivate automatic dump on startup scripts

Didn't have a lot of time to double check but pinning the pm2 version to 1.0.1 fixes it for now.

pm2::default

Recipe pm2::default keeps re-installing pm2 even if its installed on each Chef run, what is the proper way to make it skip if package already installed?

Cheers,

Update environment vars on restart --update-env ?

PM2 supports --update-env, for example...
$ ENV_VAR=somethingnew pm2 restart app --update-env

Is it possible to add another action similar to the current :restart that will support this?

We use chef to build an image that is then later used by GCE. These env vars during boot can come from an init and be different than what existed at build time.

Support for custom PM2_HOME locations

As of 0.4.0 we're overwriting the home attribute as "#{::Dir.home(new_resource.user)}/.pm2" since it's the only way PM2 is able to persist processes over reboots.

Unitech/pm2#1213 should fix this and allow to have a custom PM2_HOME to be set.

Even tho IMO we should force having the .pm2 directory always appended.

Creating this to track it.

pm2 startup centos errors for pm2 >= 2.2.1

For centos 6 systems the startup action needs to be changed to call pm2 startup centos6 instead of pm2 startup centos

With the latest version of pm2 (2.2.2), the pm2 startup centos command was updated for use with Centos 7 systemd

Unitech/pm2#2575

Any particular reason Ubuntu is not a supported OS?

I don't see Ubuntu on the list of supported OSes, but looking through the code I don't see any reason it shouldn't work for it. Was it just not an officially supported OS and/or it hasn't been tested on it?

I realize this might not be an "issue", but I don't see another place to ask this.

Thanks in advance,
Jon

Update development gem versions.

The development gems are quite outdated and should be updated to latest versions.