nibbler - npm Package Compare versions

Comparing version 0.1.1 to 0.2.0

examples/iojs-todo/README.md

+# iojs-todo
+A simple Io.js to-do application using Redis for storage.
+
+## Deploying to a remote server
+First, get a VM. Make note of its IP and access details. Make sure that port
+3000 is exposed (that's the port application listens on by default).
+
+Then, clone the Nibbler repository (`git clone https://github.com/mmalecki/nibbler`)
+and run the following in `examples/iojs-todo` directory:
+
+```sh
+npm install
+npm install nibbler-runner-ssh
+```
+
+to install all the dependencies including the SSH runner.
+
+You can now deploy the application:
+
+```sh
+npm run deploy -- --runner ssh --ssh root@host
+```
+
+To make sure that it deployed properly:
+
+```sh
+curl host:3000
+```
+
+Now you can create:
+
+```sh
+curl host:3000/todo -XPOST -H'content-type: application/json' -d '{"todo": "Learn Nibbler"}'
+```
+
+and read to-do's:
+
+```sh
+curl host:3000/todo
+```

LICENSE

+Copyright (C) 2015 by Maciej Małecki
+
+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.

examples/iojs-todo/deploy.js

@@ -1,2 +0,1 @@
-var async = require('async')
 var apt = require('nibbler-apt')
@@ -3,0 +2,0 @@ var iojs = require('nibbler-debian-iojs')

examples/iojs-todo/package.json

@@ -12,2 +12,3 @@ {
     "nibbler-apt": "~0.1.0",
+    "nibbler-copy": "~0.1.0",
     "nibbler-debian-iojs": "~0.1.0"
@@ -14,0 +15,0 @@ },

package.json

 {
   "name": "nibbler",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Simple npm-based deployment system",
@@ -21,3 +21,3 @@ "author": "Maciej Małecki <[e-mail]>",
     "nibbler-configurator": "~0.1.0",
-    "nibbler-exec": "~0.1.0"
+    "nibbler-run": "~0.1.1"
   },
@@ -24,0 +24,0 @@ "bin": {

README.md

@@ -1,12 +0,20 @@
-# nibbler
-A deployment system that's inspired by Ansible, but is modular and harnesses
-the power of npm.
+# Nibbler
+A minimal, modular, Node.js- and npm-based deployment system.
 
 ## Installation
+Globally:
+
 ```sh
-npm i nibbler
+npm install -g nibbler
 ```
 
+Or locally, as a development dependency:
+
+```sh
+npm install --save-dev nibbler
+```
+
 ## Usage
-The following playbook sets up a host with Redis and io.js present.
+The following playbook sets a host up with Redis and io.js present, and prints
+"All done" when done.
 
@@ -23,10 +31,12 @@ ```js
   } ],
-  iojs
+  iojs,
+  "echo 'All done'"
 ]
 ```
 
-If you want to run it against your local machine, simply run (given that your
-playbook file is named `playbook.js`):
+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
@@ -39,5 +49,52 @@ ```
 ```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
@@ -48,2 +105,8 @@ Handling arrays of directives isn't all that Nibbler can do. Underneath, it's
 
+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
@@ -56,8 +119,12 @@ var async = require('async')
   async.parallel([
-    async.apply(apt, {
-      updateCache: true,
-      state: 'present',
-      pkg: ['redis-server']
-    }, context),
-    async.apply(iojs, context)
+    function(next) {
+      apt({
+        updateCache: true,
+        state: 'present',
+        pkg: ['redis-server']
+      }, context, next);
+    },
+    function(next) {
+      iojs(context, next);
+    }
   ], cb)
@@ -69,1 +136,29 @@ }
 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.

New alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Fixed alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

9708

117.23%

Number of package files

9

28.57%

Number of lines in readme file

160

146.15%

Worsened metrics

Lines of code

43

-2.27%

Dependency changes

• + Added

  nibbler-run@~0.1.1

• + Added

  async@1.4.2
  (transitive)

• + Added

  nibbler-normalize@0.1.1
  (transitive)

• + Added

  nibbler-run@0.1.2
  (transitive)

• - Removed

  nibbler-exec@~0.1.0