Version information
This version is compatible with:
- Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
- Puppet >= 4.3.0 < 7.0.0
- , , ,
Start using this module
Add this module to your Puppetfile:
mod 'willdurand-nodejs', '2.1.2'
Learn more about managing modules with a PuppetfileDocumentation
puppet-nodejs
This module allows you to install Node.js and NPM. This module is published on the Puppet Forge as willdurand/nodejs.
Announcements
-
The latest release is 2.1.
-
On
master
development is happening for2.2
. -
Legacy 1.9 is still maintained, but won't receive any new features.
-
For further information, please look at the Support chapter.
Installation
The module depends on the following well-adopted and commonly used modules:
The easiest approach to install this module is by using r10k:
forge 'http://forge.puppetlabs.com'
mod 'willdurand/nodejs', '2.0.3'
mod 'puppetlabs/stdlib', '5.1.0'
Usage
Deploying a precompiled package
There are a few ways to use this puppet module. The easiest one is just using the class definition and specify a value for the version to install.
class { 'nodejs':
version => latest,
}
This installs the latest precompiled version available on nodejs.org/dist
. node
and npm
will
be available in your $PATH
at /usr/local/bin
.
There are several ways to specify a target version of node
:
version => latest
installs the latest version available.version => lts
installs the latest long-term support version.version => '9.x'
installs the latest version from thev9
series.version => '9.7
installs the latest 9.7 patch release.version => '9.9.0'
installs exactly this version.
Compiling from source
In order to compile from source with gcc
, the make_install
option must be true
.
class { 'nodejs':
version => 'lts',
make_install => true,
}
Using a custom source
It's also possible to deploy NodeJS instances to Puppet nodes from your own server. This can be helpful when e.g. distributing your own, patched version of NodeJS.
The source can be specified like this:
class { '::nodejs':
source => 'https://example.org/your-custom-nodejs-binaries.tar.gz',
}
It's also possible to compile the custom instance from source which is helpful when e.g. deploying a patched NodeJS:
class { '::nodejs':
source => 'https://example.org/node-11.0.0.tar.gz',
make_install => true,
}
Please note that the source needs to be a compressed tarball, but it doesn't matter
which format is in use (.xz
,.gz
etc). However additional packages such as xz-utils
for Debian
have to be installed manually if needed (e.g. when providing a custom source which is bundled
as .tar.xz
).
Setup with a given download timeout
Due to infrastructures with slower connections the download timeout of the nodejs binaries can be increased or disabled:
class { '::nodejs':
download_timeout => 0,
}
For further information please refer to the
timeout
docs in Puppet.
Setup multiple versions of Node.js
If you need more than one installed version of Node.js on your machine, you can
configure them using the instances
list.
class { '::nodejs':
version => lts,
instances => {
"node-lts" => {
version => lts
},
"node-9" => {
version => '9.x'
}
},
}
This will install the three specified versions (latest version, current LTS version and latest 9.x
of
NodeJS) in /usr/local/node
.
Important is that the default node
and npm
executable's versions need to be specified as
hash in the instances
list.
The structure of linked executables in /usr/local/bin
will look like this:
/usr/local/bin/node # latest (default, linked to LTS in this case)
/usr/local/bin/node-v9.x.x # latest 9.x
/usr/local/bin/node-v8.x.x # latest LTS (ATM)
/usr/local/bin/npm # NPM shipped with v8.x.x
/usr/local/bin/npm-v9.x.x # NPM shipped with NodeJS 9.x
/usr/local/bin/npm-v8.x.x # NPM shipped with NodeJS LTS
It is also possible to remove a single version like this:
class { '::nodejs':
# ...
instances_to_remove => ['9.x.x'],
}
Please keep in mind that instances_to_remove
doesn't remove version specifier like lts
or
latest
.
Setup using custom amount of cpu cores
By default, all available cpu (that are detected using the ::processorcount
fact) cores
are being used to compile nodejs. Set cpu_cores
to any number of cores you want to use.
This is mainly intended for the use with make_install => true
for parallelisation purposes.
class { 'nodejs':
version => 'lts',
cpu_cores => 2,
make_install => true,
}
Configuring $NODE_PATH
The environment variable $NODE_PATH
can be configured using the init
manifest:
class { '::nodejs':
version => 'lts',
node_path => '/your/custom/node/path',
}
It is not possible to adjust a $NODE_PATH
through ::nodejs::install
.
Binary path
node
and npm
are linked to /usr/local/bin
to be available in your system $PATH
by default. To link those binaries to a different directory such as /bin
, the parameter target_dir
can be modified accordingly:
class { 'nodejs':
version => 'lts',
target_dir => '/bin',
}
NPM Provider
NPM packages can be installed just like any else package using Puppet's package
type, but with a special provider, namely npm
:
package { 'express':
provider => npm
}
Note: When deploying a new machine without nodejs
already installed, your npm
package definition requires the nodejs class:
class { 'nodejs':
version => 'lts'
}
package { 'express':
provider => 'npm',
require => Class['nodejs']
}
NPM installer (deprecated)
Note: this API is deprecated and will be removed in 3.0
. It's recommended to either package your
applications properly using npm
and install them as package using the npm
provider or to directly
run npm install
when deploying your application (e.g. with a custom Puppet module).
This module is focused on setting up an environment with nodejs
, application deployment should be handled
in its own module. In the end this was just a wrapper on top of npm
which runs an exec
with
npm install
and a configurable user and lacks proper ensure => absent
support.
The nodejs
installer can be used if a npm package should not be installed globally, but in a
certain directory.
There are two approaches how to use this feature:
Installing a single package into a directory
::nodejs::npm { 'npm-webpack':
ensure => present, # absent would uninstall this package
pkg_name => 'webpack',
version => 'x.x', # optional
options => '-x -y -z', # CLI options passed to the "npm install" cmd, optional
exec_user => 'vagrant', # exec user, optional
directory => '/target/directory', # target directory
home_dir => '/home/vagrant', # home directory of the user which runs the installation (vagrant in this case)
}
This would install the package webpack
into /target/directory
with version x.x
.
Executing a package.json
file
::nodejs::npm { 'npm-install-dir':
list => true, # flag to tell puppet to execute the package.json file
directory => '/target',
exec_user => 'vagrant',
options => '-x -y -z',
}
Proxy
When your puppet agent is behind a web proxy, export the http_proxy
environment variable:
export http_proxy=http://myHttpProxy:8888
Skipping package setup
As discussed in willdurand/composer#44
each module should get a build_deps
parameter which can be used in edge cases in order to turn
the package setup of this module off:
class { '::nodejs':
build_deps => false,
}
In this case you'll need to take care of the following packages:
tar
wget
make
(ifmake_install
=true
)gcc
compiler (ifmake_install
=true
)
Hacking
The easiest way to get started is using bundler
:
bundle install
bundle exec rake test
PUPPET_INSTALL_TYPE=agent BEAKER_setfile=spec/acceptance/nodesets/ubuntu-1804-x64.yml bundle exec rake acceptance
Note: to run the acceptance tests that are part of rake's test
target,
Docker is required.
Authors
- William Durand (william.durand1@gmail.com)
- Johannes Graf (@grafjo)
- Maximilian Bosch (@Ma27)
Support
There are currently two main branches available, namely the 1.9
branch and 2.x
. The
support lifecycle is planned like this:
-
There's currently no plan to completely drop
1.9
. If there's demand for simple bugfixes or security-related problems, patches will be accepted and released, however there won't be any active feature development. -
Each release of
2.x
is supported until the next after the next release is published. So e.g.2.0
is supported until2.2
is published. Each release has its own branch where bugfixes can be backported, onmaster
the next minor or major release is developed. -
There's currently no plan for a next major release.
License
puppet-nodejs is released under the MIT License. See the bundled LICENSE file for details.
ChangeLog
This document lists the changes of all recent versions since 2.0.0
.
2.1.2
Bugfixes
- Allow
puppetlabs-stdlib@6.x
.
2.1.1
Bugfixes
- Fixed issue in
npm
package provider: #191
2.1.0
Minor breaking changes
- Dropped EOLed Puppet 3.x
- Don't install dev dependencies (
ruby
) anymore withbuild_deps => true
. It's only needed on the Puppet Master and shouldn't be deployed onto each node.
Other notable changes
- (#185) Allow to specify a custom source
for NodeJS to override
nodejs.org/dist
. - Don't depend on
puppetlabs-gcc
anymore. It wasn't updated by PuppetLabs since 2015 and according to its metadata it doesn't support recent Puppet version which breaks thebeaker
build.
Further changes
- Deprecated
::nodejs::npm
. The feature was always out of scope and introduced several hacks to support several edge-cases. Instead it's recommended to write a custom module suited for your application when deploying dependencies into a given directory.
2.0.3
- (#184) Added support for Puppet 6.
- (#183) Added support for
install_options
when installing a package using thenpm
provider.
2.0.2
- (#181) Instaling
rubygems
(whenbuild_deps => true
) was broken on Ubuntu 14.04. See patch b59c504 for further reference.
2.0.1
- Added support for Puppet 5.
- Install
rubygems
when allowingpuppet-nodejs
to build packages.
2.0.0
Version/Requirement changes
- Dropped support for Node.js versions until
v0.12.0
. - Dropped support for all Puppet versions below
v3.4
. - Dropped support for all ruby versions below
v2.1
.
Code changes
Installer Refactoring
- Added
puppetlabs-gcc
for package handling of the compiler (and removed custom implementation). - Killed the
python_package
option (not needed anymore). nodejs::install
has been replaced by an internal API. To use multiple instances, use theinstances
andinstances_to_remove
option of thenodejs
class (see the docs for more details).- (willdurand/puppet-composer#44) Introduced a
new
build_deps
parameter which makes the entire package setup optional.
nodejs::npm
refactoring
The nodejs::npm
resource has been refactored in order to keep the logic inside maintainable.
The following breaking changes were made:
- Removed
install_opt
andremove_opt
and replaced it with a singleoptions
parameter. - Renamed
exec_as_user
toexec_user
as it's describes the intent of the parameter in a better way. - Dropped automatic generation of a home directory for the
npm
calls and added ahome_dir
parameter which does the job. - Removed the ability to write
dir:pkg
as resource title. - The
pkg_name
has now$title
as default parameter.
Version refactoring
The whole version detection logic was quite outdated and needed a refactoring:
- Removed the
stable
flag for versions. The behavior oflatest
was equal. - Introduced the
lts
flag to fetch the latest LTS release of Node.js. - generic versions:
7.x
to fetch the latest release of the Node.js v7 branch.7.0
to fetch the latest7.0.x
release.
Other notable changes
- Removed the
::nodejs_latest_version
and::nodejs_stable_version
fact and replaced them with a puppet function to avoid evaluations on each node. - Removed
with_npm
parameter (only used for Node.js 0.6 and below). - (#94) Proper symlinks for versioned NPM executables.
- Added
cpu_cores
option to speedup the compilation process. - Changed all downloads from
http
tohttps
. - Remove installation of
git
package. - Added support for ARM architecture (
armv6l
andarmv7l
). - Added
download_timeout
parameter to simplify configuration of package download timeouts. - Dropped
profile.d
script to patch NodeJS paths. Target directory will be set withnodejs::$target_dir
which should be in$PATH
. See bcfdda3341aa8b0d885b40e9a6ab7f90859f9f3e and #177 for further reference.
Dependencies
- puppetlabs/stdlib (>= 4.12.0 < 7.0.0)
Copyright (c) William Durand <will+git@drnd.me>, Johannes Graf, Maximilian Bosch Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.