a32f34b408
Knife-Zero doesn't include Berkshelf support, so vendoring everything in the repo is convenient again
333 lines
10 KiB
Markdown
333 lines
10 KiB
Markdown
# Poise-Javascript Cookbook
|
||
|
||
[](https://travis-ci.org/poise/poise-javascript)
|
||
[](https://rubygems.org/gems/poise-javascript)
|
||
[](https://supermarket.chef.io/cookbooks/poise-javascript)
|
||
[](https://codecov.io/github/poise/poise-javascript)
|
||
[](https://gemnasium.com/poise/poise-javascript)
|
||
[](https://www.apache.org/licenses/LICENSE-2.0)
|
||
|
||
A [Chef](https://www.chef.io/) cookbook to provide a unified interface for
|
||
installing server-side JavaScript runtimes like Node.js and io.js.
|
||
|
||
## Quick Start
|
||
|
||
To install the latest available version of Node.js 0.12:
|
||
|
||
```ruby
|
||
javascript_runtime '0.12'
|
||
```
|
||
|
||
## Supported JavaScript Runtimes
|
||
|
||
This cookbook can install Node.js and io.js on Linux and OS X.
|
||
|
||
## Requirements
|
||
|
||
Chef 12.1 or newer is required.
|
||
|
||
## Attributes
|
||
|
||
Attributes are used to configure the default recipe.
|
||
|
||
* `node['poise-javascript']['install_nodejs']` – Install a Node.js runtime. *(default: true)*
|
||
* `node['poise-javascript']['install_iojs']` – Install an io.js runtime. *(default: false)*
|
||
|
||
## Recipes
|
||
|
||
### `default`
|
||
|
||
The default recipe installs Node.js or io.js based on the node attributes. It is
|
||
entirely optional and can be ignored in favor of direct use of the
|
||
`javascript_runtime` resource.
|
||
|
||
## Resources
|
||
|
||
### `javascript_runtime`
|
||
|
||
The `javascript_runtime` resource installs a JavaScript interpreter.
|
||
|
||
```ruby
|
||
javascript_runtime '0.12'
|
||
```
|
||
|
||
#### Actions
|
||
|
||
* `:install` – Install the JavaScript interpreter. *(default)*
|
||
* `:uninstall` – Uninstall the JavaScript interpreter.
|
||
|
||
#### Properties
|
||
|
||
* `version` – Version of the runtime to install. If a partial version is given,
|
||
use the latest available version matching that prefix. *(name property)*
|
||
|
||
#### Provider Options
|
||
|
||
The `poise-javascript` library offers an additional way to pass configuration
|
||
information to the final provider called "options". Options are key/value pairs
|
||
that are passed down to the `javascript_runtime` provider and can be used to control how it
|
||
installs JavaScript. These can be set in the `javascript_runtime`
|
||
resource using the `options` method, in node attributes or via the
|
||
`javascript_runtime_options` resource. The options from all sources are merged
|
||
together in to a single hash.
|
||
|
||
When setting options in the resource you can either set them for all providers:
|
||
|
||
```ruby
|
||
javascript_runtime 'myapp' do
|
||
version '0.10'
|
||
options dev_package: false
|
||
end
|
||
```
|
||
|
||
or for a single provider:
|
||
|
||
```ruby
|
||
javascript_runtime 'myapp' do
|
||
version '0.10'
|
||
options :system, dev_package: false
|
||
end
|
||
```
|
||
|
||
Setting via node attributes is generally how an end-user or application cookbook
|
||
will set options to customize installations in the library cookbooks they are using.
|
||
You can set options for all installations or for a single runtime:
|
||
|
||
```ruby
|
||
# Global, for all installations.
|
||
override['poise-javascript']['options']['version'] = '0.10'
|
||
# Single installation.
|
||
override['poise-javascript']['myapp']['version'] = 'iojs'
|
||
```
|
||
|
||
The `javascript_runtime_options` resource is also available to set node attributes
|
||
for a specific installation in a DSL-friendly way:
|
||
|
||
```ruby
|
||
javascript_runtime_options 'myapp' do
|
||
version 'iojs'
|
||
end
|
||
```
|
||
|
||
Unlike resource attributes, provider options can be different for each provider.
|
||
Not all providers support the same options so make sure to the check the
|
||
documentation for each provider to see what options the use.
|
||
|
||
### `javascript_runtime_options`
|
||
|
||
The `javascript_runtime_options` resource allows setting provider options in a
|
||
DSL-friendly way. See [the Provider Options](#provider-options) section for more
|
||
information about provider options overall.
|
||
|
||
```ruby
|
||
javascript_runtime_options 'myapp' do
|
||
version 'iojs'
|
||
end
|
||
```
|
||
|
||
#### Actions
|
||
|
||
* `:run` – Apply the provider options. *(default)*
|
||
|
||
#### Properties
|
||
|
||
* `resource` – Name of the `javascript_runtime` resource. *(name property)*
|
||
* `for_provider` – Provider to set options for.
|
||
|
||
All other attribute keys will be used as options data.
|
||
|
||
### `javascript_execute`
|
||
|
||
The `javascript_execute` resource executes a JavaScript script using the configured runtime.
|
||
|
||
```ruby
|
||
javascript_execute 'myapp.js' do
|
||
user 'myuser'
|
||
end
|
||
```
|
||
|
||
This uses the built-in `execute` resource and supports all the same properties.
|
||
|
||
#### Actions
|
||
|
||
* `:run` – Execute the script. *(default)*
|
||
|
||
#### Properties
|
||
|
||
* `command` – Script and arguments to run. Must not include the `node`. *(name attribute)*
|
||
* `javascript` – Name of the `javascript_runtime` resource to use. If not specified, the
|
||
most recently declared `javascript_runtime` will be used. Can also be set to the
|
||
full path to a `node` binary.
|
||
|
||
For other properties see the [Chef documentation](https://docs.chef.io/resource_execute.html#attributes).
|
||
|
||
### `node_package`
|
||
|
||
The `node_package` resource installs Node.js packages using
|
||
[NPM](https://www.npmjs.com/).
|
||
|
||
```ruby
|
||
node_package 'express' do
|
||
version '4.13.3'
|
||
end
|
||
```
|
||
|
||
This uses the built-in `package` resource and supports the same actions and
|
||
properties. Multi-package installs are supported using the standard syntax.
|
||
|
||
#### Actions
|
||
|
||
* `:install` – Install the package. *(default)*
|
||
* `:upgrade` – Upgrade the package.
|
||
* `:remove` – Uninstall the package.
|
||
|
||
The `:purge` and `:reconfigure` actions are not supported.
|
||
|
||
#### Properties
|
||
|
||
* `group` – System group to install the package.
|
||
* `package_name` – Package or packages to install. *(name property)*
|
||
* `path` – Path to install the package in to. If unset install using `--global`.
|
||
*(default: nil)*
|
||
* `version` – Version or versions to install.
|
||
* `javascript` – Name of the `javascript_runtime` resource to use. If not specified, the
|
||
most recently declared `javascript_runtime` will be used. Can also be set to the
|
||
full path to a `node` binary.
|
||
* `unsafe_perm` – Enable `--unsafe-perm`. *(default: true)*
|
||
* `user` – System user to install the package.
|
||
|
||
For other properties see the [Chef documentation](https://docs.chef.io/resource_package.html#attributes).
|
||
The `response_file`, `response_file_variables`, and `source` properties are not
|
||
supported.
|
||
|
||
### `npm_install`
|
||
|
||
The `npm_install` resource runs `npm install` for a package.
|
||
|
||
```ruby
|
||
npm_install '/opt/myapp'
|
||
```
|
||
|
||
The underlying `npm install` command will run on every converge, but notifications
|
||
will only be triggered if a package is actually installed.
|
||
|
||
#### Actions
|
||
|
||
* `:install` – Run `npm install`. *(default)*
|
||
|
||
#### Properties
|
||
|
||
* `path` – Path to the package folder containing a `package.json`. *(name attribute)*
|
||
* `group` – System group to install the packages.
|
||
* `javascript` – Name of the `javascript_runtime` resource to use. If not specified, the
|
||
most recently declared `javascript_runtime` will be used. Can also be set to the
|
||
full path to a `node` binary.
|
||
* `production` – Enable production install mode. *(default: true)*
|
||
* `unsafe_perm` – Enable `--unsafe-perm`. *(default: true)*
|
||
* `user` – System user to install the packages.
|
||
|
||
## Javascript Providers
|
||
|
||
### Common Options
|
||
|
||
These provider options are supported by all providers.
|
||
|
||
* `version` – Override the runtime version.
|
||
|
||
### `system`
|
||
|
||
The `system` provider installs Node.js using system packages. This is currently
|
||
only tested on platforms using `apt-get` and `yum` (Debian, Ubuntu, RHEL, CentOS
|
||
Amazon Linux, and Fedora). It may work on other platforms but is untested.
|
||
|
||
```ruby
|
||
javascript_runtime 'myapp' do
|
||
provider :system
|
||
version '0.10'
|
||
end
|
||
```
|
||
|
||
#### Options
|
||
|
||
* `dev_package` – Install the package with the headers and other development
|
||
files. Can be set to a string to select the dev package specifically.
|
||
*(default: true)*
|
||
* `package_name` – Override auto-detection of the package name.
|
||
* `package_upgrade` – Install using action `:upgrade`. *(default: false)*
|
||
* `package_version` – Override auto-detection of the package version.
|
||
|
||
### `scl`
|
||
|
||
The `scl` provider installs Node.js using the [Software Collections](https://www.softwarecollections.org/)
|
||
packages. This is only available on RHEL and CentOS. SCL offers more
|
||
recent versions of Node.js than the system packages for the most part. If an SCL
|
||
package exists for the requests version, it will be used in preference to the
|
||
`system` provider.
|
||
|
||
```ruby
|
||
javascript_runtime 'myapp' do
|
||
provider :scl
|
||
version '0.10'
|
||
end
|
||
```
|
||
|
||
### `nodejs`
|
||
|
||
The `nodejs` provider installs Node.js from the static binaries on nodejs.org.
|
||
Support is included for Linux and OS X.
|
||
|
||
```ruby
|
||
javascript_runtime 'myapp' do
|
||
provider :nodejs
|
||
version '0.12'
|
||
end
|
||
```
|
||
|
||
#### Options
|
||
|
||
* `path` – Folder to install Node.js to. *(default: /opt/nodejs-<version>)*
|
||
* `static_version` – Specific version number to use for computing the URL and
|
||
path. *(default: automatic from `version`)*
|
||
* `strip_components` – Value to pass to tar --strip-components. *(automatic)*
|
||
* `url` – URL template to download the archive from. *(default: automatic)*
|
||
|
||
### `iojs`
|
||
|
||
The `iojs` provider installs io.js from the static binaries on iojs.org.
|
||
Support is included for Linux and OS X.
|
||
|
||
```ruby
|
||
javascript_runtime 'myapp' do
|
||
provider :iojs
|
||
version '3'
|
||
end
|
||
```
|
||
|
||
#### Options
|
||
|
||
* `path` – Folder to install io.js to. *(default: /opt/iojs-<version>)*
|
||
* `static_version` – Specific version number to use for computing the URL and
|
||
path. *(default: automatic from `version`)*
|
||
* `strip_components` – Value to pass to tar --strip-components. *(automatic)*
|
||
* `url` – URL template to download the archive from. *(default: automatic)*
|
||
|
||
## Sponsors
|
||
|
||
The Poise test server infrastructure is sponsored by [Rackspace](https://rackspace.com/).
|
||
|
||
## License
|
||
|
||
Copyright 2015-2017, Noah Kantrowitz
|
||
|
||
Licensed under the Apache License, Version 2.0 (the "License");
|
||
you may not use this file except in compliance with the License.
|
||
You may obtain a copy of the License at
|
||
|
||
http://www.apache.org/licenses/LICENSE-2.0
|
||
|
||
Unless required by applicable law or agreed to in writing, software
|
||
distributed under the License is distributed on an "AS IS" BASIS,
|
||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
See the License for the specific language governing permissions and
|
||
limitations under the License.
|