Vendor the external cookbooks
Knife-Zero doesn't include Berkshelf support, so vendoring everything in the repo is convenient again
This commit is contained in:
Greg Karékinian
332
cookbooks/poise-javascript/README.md
Normal file
332
cookbooks/poise-javascript/README.md
Normal file
@@ -0,0 +1,332 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user