# nibbler

> Simple npm-based deployment system

Latest version **0.2.0** (published 2015-08-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install nibbler
pnpm add nibbler
yarn add nibbler
bun add nibbler
```

Provides the command `nibbler`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2015-08-10 |
| First published | 2015-04-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 22 |
| Author | Maciej Małecki |
| Maintainers | mmalecki |

## Links

- npm: https://www.npmjs.com/package/nibbler
- Repository: https://github.com/mmalecki/nibbler
- Issues: https://github.com/mmalecki/nibbler/issues
- npm.io page: https://npm.io/package/nibbler

## Dependencies (2)

- [nibbler-run](https://npm.io/package/nibbler-run.md) ~0.1.1
- [nibbler-configurator](https://npm.io/package/nibbler-configurator.md) ~0.1.0

## Recent versions

- 0.2.0 (latest) — 2015-08-10
- 0.1.1 — 2015-04-21
- 0.1.0 — 2015-04-20

## README

# Nibbler
A minimal, modular, Node.js- and npm-based deployment system.

## Installation
Globally:

```sh
npm install -g nibbler
```

Or locally, as a development dependency:

```sh
npm install --save-dev nibbler
```

## Usage
The following playbook sets a host up with Redis and io.js present, and prints
"All done" when done.

```js
var apt = require('nibbler-apt')
var iojs = require('nibbler-debian-iojs')

module.exports = [
  [ apt, {
    updateCache: true,
    state: 'present',
    pkg: ['redis-server']
  } ],
  iojs,
  "echo 'All done'"
]
```

If you want to run it against your local Debian machine, simply run (given that
your playbook file is named `playbook.js`):

```sh
npm install nibbler-runner-local nibbler-apt nibbler-debian-iojs
nibbler playbook.js
```

If you desire to bootstrap a remote host (all actions happen through SSH, so no
binaries are required on remote side):

```sh
npm install nibbler-runner-ssh nibbler-apt nibbler-debian-iojs
nibbler --runner ssh --ssh root@122.65.21.42 playbook.js
```

### More examples
There are more complex examples in the [`examples`](https://github.com/mmalecki/nibbler/tree/master/examples/)
directory:

* [`iojs-todo`](https://github.com/mmalecki/nibbler/tree/master/examples/iojs-todo) - a simple Io.js to-do application.

### Runners
The only thing that Nibbler core does is provide you with a JavaScript DSL for
running actions in series, and easy execution of commands through a runner. All
the logic involved with running commands on a remote (for example, a SSH-enabled
host or a Docker container) lives in runners.

Runner is a module which receives a Nibbler context descriptor (containing
command line options, environment, whether to use `sudo` globally, etc.) and
returns a `child_process`-like API.

So, for example, the local runner is as simple as this:

```js
module.exports = function(context) {
  return require('child_process')
}
```

At the moment, the notable runners are:

* [`nibbler-runner-ssh`](https://www.npmjs.com/package/nibbler-runner-ssh) - SSH runner
* [`nibbler-runner-local`](https://www.npmjs.com/package/nibbler-runner-local) - local runner

### Useful helpers
Nibbler comes with no core modules. There are, however, numerous helpers you
can use:

* [`nibbler-exec`](https://www.npmjs.com/package/nibbler-exec) - execute commands
  with regard for global `sudo`
* [`nibbler-apt`](https://www.npmjs.com/package/nibbler-apt) - manage Apt packages
* [`nibbler-copy`](https://www.npmjs.com/package/nibbler-copy) - copy local directories
  and files
* [`nibbler-debian-iojs`](https://www.npmjs.com/package/nibbler-debian-iojs) -
  install Io.js on a Debian host
* [`nibbler-upstart`](https://www.npmjs.com/package/nibbler-upstart) - install,
  start and stop Upstart services

In general, you should be able to find Nibbler modules by
[searching for "nibbler" on npm](https://www.npmjs.com/search?q=nibbler).

### Fancying up
Handling arrays of directives isn't all that Nibbler can do. Underneath, it's
all JavaScript, and Nibbler is specifically designed so that dropping down to
it is as easy as it gets.

If `module.exports` of your playbook is a function, Nibbler will call it with
the context object and a callback. The context object looks as follows:

* `runner` - a `child_process`-like API provided by your runner of choic
* `sudo` - a `Boolean` indicating whether user requested global sudo

```js
var async = require('async')
var apt = require('nibbler-apt')
var iojs = require('nibbler-debian-iojs')
 
module.exports = function(context, cb) {
  async.parallel([
    function(next) {
      apt({
        updateCache: true,
        state: 'present',
        pkg: ['redis-server']
      }, context, next);
    },
    function(next) {
      iojs(context, next);
    }
  ], cb)
}
```

This example has the added benefit of running all the actions in parallel.
You can run it in the same exact way.

## Rationale
I was looking for a minimal deployment tool with a way to modularize and
parametrize deployment. I've looked at several available solutions, considering
the size of the ecosystem and tool's integration with it, the module manager
and general architecture and found nothing that I liked. Specifically:

  * Ansible - to write modules (instead of roles, which are YAML) you need to
    write Python and deal with Ansible's module path. Built-in inventory support.
    Package management is for roles, not modules. YAML.

  * Chef - Ruby. Hard to reuse generic Ruby Gems because of the DSL.

  * Puppet - YAML and DSL.

So I decided to build something like that. What distinguishes Nibbler from the
rest:

  * Integration with the ecosystem. Nibbler uses Node.js and instead of
    creating a DSL for performing actions on remote servers, Nibbler
    uses runners, which implement Node.js `child_process` API but act on the remote.

  * npm. Nibbler and its modules are all in npm. You can install them as
    development dependencies. Nibbler modules heavily reuse existing npm modules.
    This also means no core modules - core is where modules die.

Those two things allowed me to develop modules and deploy really fast - using
APIs and ecosystems which I didn't have to learn allowed me to move quicker.

---
_Source: https://npm.io/package/nibbler · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._