serverkit 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8a305e729177502f64c869b2629dd30acfad21ae
-  data.tar.gz: 712936e178cf102fd9725046027f9cb7e96d7fca
+  metadata.gz: 24b5913dfd17ab82dcc688aba30f392c4fb36f02
+  data.tar.gz: b80f8bd60e1a500e5ca7b497d90c0d26144207e6
 SHA512:
-  metadata.gz: c1618d46d882bec5251d762b954341f326fb94aaba997bff66e3358306b5da5392c7a4d9714bd45d6a4bd93bf7fbc3b255a132995822954b2cbb5e7d40f2a1d2
-  data.tar.gz: b27a2c2ee0062256bcfea32e61658e0a5a8eb912e01d30bb0573165f0ef69afdc76c58ffd7192a51c9c3d6617b2eb5fca1518ec964c3b35684fa9baf9c5c9d56
+  metadata.gz: 750ad9c4d49922d310ac45455566c78f98871c10318f751a8dfcbc41b5a7b597759b889df73de3167d0c0ddc94dc851e4ca62f70d24b350d5eb1c0df833dd4c4
+  data.tar.gz: 5054ae0860bfe29c22e489cc5f3efd55273bedc304d172595c7cb8a9c5c1bd0cd5eb5906d61ef3404b3c48fb8fa32babc29e9527cc6afaf2e7123d2dc5c2b2dc

data/.gitignore

@@ -3,7 +3,6 @@
 /.vagrant
 /.yardoc
 /coverage/
-/doc/
 /Gemfile.lock
 /pkg/
 /spec/reports/

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 0.5.1
+- Fix user resource behavior on nil password case
+
 ## 0.5.0
 - Add validation_script attribute on line resource
 
@@ -31,7 +34,7 @@
 - Change some attribue names on user resource
 
 ## 0.4.2
-- Fix bug on apply action exit code
+- Fix bug on apply action exit status
 - Support case-insensitive or number log-level
 
 ## 0.4.1
@@ -51,7 +54,7 @@
 - Change attributes naming rule: status -> state
 
 ## 0.3.3
-- Return exit code 1 if any resource failed
+- Return exit status 1 if any resource failed
 
 ## 0.3.2
 - Fix git resource on git-clone

data/README.md

@@ -1,288 +1,56 @@
 # Serverkit [![Build Status](https://travis-ci.org/r7kamura/serverkit.svg)](https://travis-ci.org/r7kamura/serverkit) [![Code Climate](https://codeclimate.com/github/r7kamura/serverkit/badges/gpa.svg)](https://codeclimate.com/github/r7kamura/serverkit)
-Configuration management toolkit for IT automation.
+Assemble servers from your recipe.
 
-- [Usage](#usage)
-  - [serverkit validate](#serverkit-validate)
-  - [serverkit inspect](#serverkit-inspect)
-  - [serverkit check](#serverkit-check)
-  - [serverkit apply](#serverkit-apply)
-  - [SSH support](#ssh-support)
-  - [Log](#log)
-- [Recipe](#recipe)
-  - [Format](#format)
-  - [Variables](#variables)
-  - [Example](#example)
-- [Resource](#resource)
-  - [Attributes](#attributes)
-  - [Type](#type)
-  - [Example](#example-1)
-- [Handler](#handler)
-- [Plug-in](#plug-in)
-- [Vagrant](#vagrant)
+![Server (thx 1041uuu)](/images/server.png)
 
 ## Usage
-Write a recipe, then run `serverkit` executable to validate, inspect, check, and apply the recipe.
+Describe the desired state, then `serverkit apply`.
 
-### serverkit validate
-Validates recipe schema, resources, and attributes.
-For instance, it shows validation error if `source` attributes is missing in `remote_file` resource.
-If any validation error is detected, it returns exit status 1.
-
-```
-$ serverkit validate recipe.yml
-Error: source attribute is required in remote_file resource
-Error: path attribute can't be unreadable path in recipe resource
-```
-
-### serverkit inspect
-Shows fully-expanded recipe data in JSON format.
-
-```
-$ serverkit inspect recipe.yml
-{
-  "resources": [
-    {
-      "type": "homebrew",
-      "name": "mysql"
-    },
-    {
-      "type": "homebrew",
-      "name": "redis"
-    },
-    {
-      "type": "homebrew_cask",
-      "name": "licecap"
-    },
-    {
-      "type": "homebrew_cask",
-      "name": "alfred"
-    },
-    {
-      "type": "git",
-      "repository": "git@github.com:r7kamura/dotfiles.git",
-      "path": "/Users/r7kamura/src/github.com/r7kamura/dotfiles"
-    },
-    {
-      "type": "symlink",
-      "source": "/Users/r7kamura/.zshrc",
-      "destination": "/Users/r7kamura/src/github.com/r7kamura/dotfiles/linked/.zshrc"
-    }
-  ]
-}
-```
-
-### serverkit check
-Shows the difference between your recipe and the state of the target host.
-If any difference is detected, it returns exit status 1.
-
-```
-$ serverkit check recipe.yml
-[ OK ] homebrew mysql on localhost
-[ OK ] homebrew redis on localhost
-[ OK ] homebrew_cask licecap on localhost
-[ OK ] homebrew_cask alfred on localhost
-[ NG ] git git@github.com:r7kamura/dotfiles.git on localhost
-[ NG ] symlink /Users/r7kamura/src/github.com/r7kamura/dotfiles/linked/.zshrc on localhost
-```
-
-### serverkit apply
-Executes migration process to fill-in the gaps.
-If any failure is detected, it returns exit status 1.
-
-```
-$ serverkit apply recipe.yml
-[SKIP] homebrew mysql on localhost
-[SKIP] homebrew redis on localhost
-[SKIP] homebrew_cask licecap on localhost
-[SKIP] homebrew_cask alfred on localhost
-[DONE] git git@github.com:r7kamura/dotfiles.git on localhost
-[DONE] symlink /Users/r7kamura/src/github.com/r7kamura/dotfiles/linked/.zshrc on localhost
-```
-
-### SSH support
-Use `--hosts=` option to execute serverkit over SSH.
-Serverkit does not require any installation on server-side.
-If you want to specify SSH configuration, write it into your ~/.ssh/config.
-
-```
-$ serverkit apply recipe.yml --hosts=alpha.example.com
-$ serverkit apply recipe.yml --hosts=alpha.example.com,bravo.example.com
-```
-
-### Log
-You can change serverkit log level by passing `--log-level=` command line option.
-Available values are `DEBUG`, `ERROR`, `FATAL`, `WARN`, OR `INFO` (default).
-General result lines like `[SKIP] ...` and `[ OK ] ...` are logged with FATAL level,
-and all shell commands executed on hosts are logged with DEBUG level.
-Pass `--no-color` option if you would like to disable colored log outputs.
-
-```
-$ serverkit apply recipe.yml --hosts=alpha.example.com --log-level=debug --no-color
-```
-
-## Recipe
-A recipe describes the desired state of your server.
-It is mostly a collection of resources, defined using certain patterns.
-
-### Format
-A recipe can be specified as a path to one of the following patterns:
-
-- JSON file
-- YAML file named with \*.yaml or \*.yml
-- ERB file named with \*.json.erb or \*.yml.erb
-- Executable to output JSON
-- Directory including recipe files recursively
-
-```
-$ serverkit apply recipe
-$ serverkit apply recipe.json
-$ serverkit apply recipe.json.erb
-$ serverkit apply recipe.json.erb --variables=variables
-$ serverkit apply recipe.json.erb --variables=variables.json
-$ serverkit apply recipe.json.erb --variables=variables.json.erb
-$ serverkit apply recipe.json.erb --variables=variables.yml
-$ serverkit apply recipe.json.erb --variables=variables.yml.erb
-$ serverkit apply recipe.json.erb --variables=variables/
-$ serverkit apply recipe.yml
-$ serverkit apply recipe.yml.erb
-$ serverkit apply recipes/
-```
-
-### Variables
-When using ERB recipe, you can also give optional variables file
-that defines configurations in a Hash object for ERB template.
-It supports similar format variation with Recipe.
-In ERB template, you can use given variables via methods named after its keys.
-
-### Example
-This is an example recipe to install some packages, clone a git repository, and create a symlink.
-
-```yml
-# variables.yml
-dotfiles_repository: r7kamura/dotfiles
-user: r7kamura
-```
-
-```yml
-# recipe.yml.erb
+```sh
+$ echo '
 resources:
   - type: package
     name: mysql
   - type: package
     name: redis
-  - type: git
-    repository: git@github.com:<%= dotfiles_repository %>.git
-    path: /Users/<%= user %>/src/github.com/<%= dotfiles_repository %>
-  - type: symlink
-    source: /Users/<%= user %>/.zshrc
-    destination: /Users/<%= user %>/src/github.com/<%= dotfiles_repository %>/.zshrc
-```
-
-## Resource
-A resource is a statement of configuration policy that describes the desired state for an item.
-
-### Attributes
-Each resource has different attributes along with its type.
-By default, all types of resource can or must have the following attributes:
-
-- type - what type this resource represents (required)
-- check_script - pass shell script to override the `#check` phase
-- recheck_script - pass shell script to override the `#recheck` phase (runned after `#apply`)
-- id - change resource identifier used in log, and also used for `notify`
-- notify - specify an Array of handler ids that should be applied after changed
-
-### Type
-A resource must have a valid type attribute like:
-
-- [command](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/command.rb)
-- [directory](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/directory.rb)
-- [file](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/file.rb)
-- [git](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/git.rb)
-- [group](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/group.rb)
-- [line](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/line.rb)
-- [nothing](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/nothing.rb)
-- [package](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/package.rb)
-- [recipe](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/recipe.rb)
-- [remote_file](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/remote_file.rb)
-- [service](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/service.rb)
-- [symlink](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/symlink.rb)
-- [template](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/template.rb)
-- [user](https://github.com/r7kamura/serverkit/blob/master/lib/serverkit/resources/user.rb)
-
-### Example
-An example package resource that has type and name attributes.
-
-```yml
-resources:
-  - type: package
-    name: mysql
-```
-
-## Handler
-When any changes are successfully applied to a resource and it has notify attribute,
-it notifies handlers that are referenced by their id.
-The notified handlers will run only once after all resources finished their applications.
-Here's an example of restarting Dock on Mac OS X when its preferences change.
-
-```yml
-resources:
-  - type: defaults
-    domain: com.apple.dock
-    key: autohide
-    value: 1
-    notify:
-      - restart_dock
-  - type: defaults
-    domain: com.apple.dock
-    key: persistent-apps
-    value: []
-    notify:
-      - restart_dock
-handlers:
-  - id: restart_dock
-    type: command
-    script: killall Dock
-```
-
-## Plug-in
-A plug-in is provided as a gem.
-Serverkit calls `Bundler.require(:default)` before running an action,
-so you can add any behaviors to serverkit via gems defined in Gemfile.
-For example, [serverkit-rbenv](https://github.com/r7kamura/serverkit-rbenv) gem
-adds a custom resource type named `rbenv_ruby` by defining `Serverkit::Resources::RbenvRuby` class.
-Serverkit finds `Serverkit::Resources::FooBar` resource class from `type: "foo_bar"`.
-
-- [serverkit-atom](https://github.com/r7kamura/serverkit-atom)
-- [serverkit-defaults](https://github.com/r7kamura/serverkit-defaults)
-- [serverkit-homebrew](https://github.com/r7kamura/serverkit-homebrew)
-- [serverkit-karabiner](https://github.com/r7kamura/serverkit-karabiner)
-- [serverkit-rbenv](https://github.com/r7kamura/serverkit-rbenv)
-
-```rb
-# Gemfile
-gem "serverkit"
-gem "serverkit-atom"
-gem "serverkit-defaults"
-gem "serverkit-homebrew"
-gem "serverkit-karabiner"
-gem "serverkit-rbenv"
-```
-
-## Vagrant
-[vagrant-serverkit](https://github.com/r7kamura/vagrant-serverkit)
-helps you provision your vagrant box with serverkit.
-
-```rb
-# Vagrantfile
-Vagrant.configure("2") do |config|
-  config.vm.box = "ubuntu/trusty64"
-  config.vm.provision :serverkit do |serverkit_config|
-    serverkit_config.recipe_path = "recipe.yml"
-  end
-end
+' > recipe.yml
+$ serverkit apply recipe.yml
 ```
 
-```
-$ vagrant plugin install vagrant-serverkit
-$ vagrant up
-```
+## Documentation
+- [Install](/doc/install.md)
+- [serverkit apply](/doc/action_apply.md)
+- [serverkit check](/doc/action_check.md)
+- [serverkit inspect](/doc/action_inspect.md)
+- [serverkit validate](/doc/action_validate.md)
+- [Recipe](/doc/recipe.md)
+- [Resource](/doc/resource.md)
+ - [command](/doc/resource_command.md)
+ - [directory](/doc/resource_directory.md)
+ - [file](/doc/resource_file.md)
+ - [git](/doc/resource_git.md)
+ - [group](/doc/resource_group.md)
+ - [line](/doc/resource_line.md)
+ - [nothing](/doc/resource_nothing.md)
+ - [package](/doc/resource_package.md)
+ - [recipe](/doc/resource_recipe.md)
+ - [remote_file](/doc/resource_remote_file.md)
+ - [service](/doc/resource_service.md)
+ - [symlink](/doc/resource_symlink.md)
+ - [template](/doc/resource_template.md)
+ - [user](/doc/resource_user.md)
+- [Plug-in](/doc/plug_in.md)
+ - [serverkit-atom](https://github.com/r7kamura/serverkit-atom)
+ - [serverkit-defaults](https://github.com/r7kamura/serverkit-defaults)
+ - [serverkit-homebrew](https://github.com/r7kamura/serverkit-homebrew)
+ - [serverkit-karabiner](https://github.com/r7kamura/serverkit-karabiner)
+ - [serverkit-rbenv](https://github.com/r7kamura/serverkit-rbenv)
+ - [serverkit-login_items](https://github.com/take/serverkit-login_items)
+- [Vagrant integration](/doc/vagrant_integration.md)
+
+## Similar tools
+- [ansible/ansible](https://github.com/ansible/ansible)
+- [fabric/fabric](https://github.com/fabric/fabric)
+- [chef/chef](https://github.com/chef/chef)
+- [puppetlabs/puppet](https://github.com/puppetlabs/puppet)
+- [itamae-kitchen/itamae](https://github.com/itamae-kitchen/itamae)

data/Vagrantfile

@@ -4,9 +4,10 @@ Vagrant.configure("2") do |config|
   config.plugin.add_dependency "vagrant-multiplug"
   config.plugin.add_dependency "vagrant-serverkit", "0.0.5"
 
-  config.vm.provision :serverkit do |serverkit_config|
-    serverkit_config.log_level = "DEBUG"
-    serverkit_config.recipe_path = "example/recipe.yml"
-    serverkit_config.variables_path = "example/variables.yml"
-  end
+  config.vm.provision(
+    :serverkit,
+    log_level: "DEBUG",
+    recipe_path: "example/recipe.yml",
+    variables_path: "example/variables.yml",
+  )
 end

data/doc/action_apply.md

@@ -0,0 +1,58 @@
+# serverkit apply
+`serverkit apply` is an executable action to execute migration process to fill-in the gaps
+between the specified recipe and the state of the target host.
+
+## Successful case
+If no error was found, it returns exit status 0.
+
+```
+$ serverkit apply recipe.yml
+[SKIP] homebrew mysql on localhost
+[SKIP] homebrew redis on localhost
+[SKIP] homebrew_cask licecap on localhost
+[SKIP] homebrew_cask alfred on localhost
+[DONE] git git@github.com:r7kamura/dotfiles.git on localhost
+[DONE] symlink /Users/r7kamura/src/github.com/r7kamura/dotfiles/linked/.zshrc on localhost
+$ echo $?
+0
+```
+
+## Failed case
+If any error was found, it returns exit status 1.
+
+```
+$ serverkit apply recipe.yml
+[SKIP] homebrew mysql on localhost
+[SKIP] homebrew redis on localhost
+[SKIP] homebrew_cask licecap on localhost
+[SKIP] homebrew_cask alfred on localhost
+[FAIL] git git@github.com:r7kamura/dotfiles.git on localhost
+[DONE] symlink /Users/r7kamura/src/github.com/r7kamura/dotfiles/linked/.zshrc on localhost
+$ echo $?
+1
+```
+
+## --hosts= option
+Use `--hosts=` option to execute serverkit over SSH.
+Serverkit does not require any installation on server-side.
+You can run serverkit on multiple hosts by passing hosts in comma-separated style.
+If you want to specify SSH configuration, write it into your ~/.ssh/config.
+This option is also available in `serverkit check` action.
+
+```
+$ serverkit apply recipe.yml --hosts=alpha.example.com
+$ serverkit apply recipe.yml --hosts=alpha.example.com,bravo.example.com
+$ serverkit apply recipe.yml --hosts=app1,app2,app3
+```
+
+## --log-level option
+You can change serverkit log level by passing `--log-level=` option with
+`DEBUG`, `ERROR`, `FATAL`, `WARN`, or `INFO` (case-insensitive, and the default is `INFO`).
+For example, the general result lines like `[SKIP] ...` and `[ OK ] ...` are logged with FATAL level,
+and all shell commands executed on hosts are logged with DEBUG level.
+The log output is colored by default.
+Pass `--no-color` option if you want to disable colored log outputs.
+
+```
+$ serverkit apply recipe.yml --hosts=alpha.example.com --log-level=debug --no-color
+```

data/doc/action_check.md

@@ -0,0 +1,36 @@
+# serverkit check
+`serverkit check` is an executable action to show the difference between the specified recipe and
+the state of the target host (a.k.a. "dry-run" in other tools).
+Note that this action might do some destructive behaviors by resource implementations (e.g. `git fetch`).
+This action takes the same options with `serverkit apply` action.
+See [/doc/action_apply.md] for more details.
+
+## Same case
+If no difference was detected, it returns exit status 0.
+
+```
+$ serverkit check recipe.yml
+[ OK ] homebrew mysql on localhost
+[ OK ] homebrew redis on localhost
+[ OK ] homebrew_cask licecap on localhost
+[ OK ] homebrew_cask alfred on localhost
+[ OK ] git git@github.com:r7kamura/dotfiles.git on localhost
+[ OK ] symlink /Users/r7kamura/src/github.com/r7kamura/dotfiles/linked/.zshrc on localhost
+$ echo $?
+0
+```
+
+## Different case
+If any difference was detected, it returns exit status 1.
+
+```
+$ serverkit check recipe.yml
+[ OK ] homebrew mysql on localhost
+[ OK ] homebrew redis on localhost
+[ OK ] homebrew_cask licecap on localhost
+[ OK ] homebrew_cask alfred on localhost
+[ NG ] git git@github.com:r7kamura/dotfiles.git on localhost
+[ NG ] symlink /Users/r7kamura/src/github.com/r7kamura/dotfiles/linked/.zshrc on localhost
+$ echo $?
+1
+```

data/doc/action_inspect.md

@@ -0,0 +1,39 @@
+# serverkit inspect
+`serverkit inspect` is an executable action to show fully-expanded recipe content in JSON format.
+This action is useful as your recipe grows to a large size with using variables, nested recipe, and so on.
+You can specify your recipe by passing its path in the same way as the other actions.
+
+## Example
+```
+$ serverkit inspect recipe.yml
+{
+  "resources": [
+    {
+      "type": "homebrew",
+      "name": "mysql"
+    },
+    {
+      "type": "homebrew",
+      "name": "redis"
+    },
+    {
+      "type": "homebrew_cask",
+      "name": "licecap"
+    },
+    {
+      "type": "homebrew_cask",
+      "name": "alfred"
+    },
+    {
+      "type": "git",
+      "repository": "git@github.com:r7kamura/dotfiles.git",
+      "path": "/Users/r7kamura/src/github.com/r7kamura/dotfiles"
+    },
+    {
+      "type": "symlink",
+      "source": "/Users/r7kamura/.zshrc",
+      "destination": "/Users/r7kamura/src/github.com/r7kamura/dotfiles/linked/.zshrc"
+    }
+  ]
+}
+```

data/doc/action_validate.md

@@ -0,0 +1,24 @@
+# serverkit validate
+`serverkit validate` is an executable action to check if a specified recipe is valid or not.
+You can specify your recipe by passing its path in the same way as the other actions.
+Note that the other actions (e.g. `inspect`, `check`, `apply`) also runs validation before its task.
+
+## Successful case
+If no error found, it returns exit status 0.
+
+```
+$ serverkit validate recipe.yml
+$ echo $?
+0
+```
+
+## Failed case
+If any error found, it reports errors and returns exit status 1.
+
+```
+$ serverkit validate recipe.yml
+Error: source attribute is required in remote_file resource
+Error: path attribute can't be unreadable path in recipe resource
+$ echo $?
+1
+```

data/doc/install.md

@@ -0,0 +1,38 @@
+# Install
+## Prerequisites
+Ruby 2.0.0 or later is required.
+
+## via Bundler
+We recommend you to use [bundler](http://bundler.io/) to install serverkit and its plugins,
+and run serverkit via `bundle exec serverkit`.
+
+```rb
+# Gemfile
+source "https://rubygems.org"
+gem "serverkit"
+```
+
+```
+$ gem install bundler
+$ bundle install
+```
+
+## via Gem
+Instead you can simply install serverkit by `gem` command,
+while you cannot use plugins without bundler.
+
+```
+$ gem install serverkit
+```
+
+## via Source
+If you want to install serverkit from source code for any reason,
+you can `git clone` the source code and `rake install` it.
+bundler and git are both required in this method.
+
+```
+$ git clone https://github.com/r7kamura/serverkit.git
+$ cd serverkit
+$ bundle install
+$ bundle exec rake install
+```

data/doc/plug_in.md

@@ -0,0 +1,18 @@
+# Plug-in
+A serverkit plug-in is provided as a gem.
+Serverkit calls `Bundler.require(:default)` before running an action,
+so you can add any behaviors to serverkit via gems defined in Gemfile.
+For example, [serverkit-rbenv](https://github.com/r7kamura/serverkit-rbenv) gem
+adds a custom resource type named `rbenv_ruby` by defining `Serverkit::Resources::RbenvRuby` class.
+Serverkit finds `Serverkit::Resources::FooBar` resource class from `type: "foo_bar"`.
+
+```rb
+# Gemfile
+gem "serverkit"
+gem "serverkit-atom"
+gem "serverkit-defaults"
+gem "serverkit-homebrew"
+gem "serverkit-karabiner"
+gem "serverkit-rbenv"
+gem "serverkit-login_items"
+```

data/doc/recipe.md

@@ -0,0 +1,75 @@
+# Recipe
+A recipe describes the desired state of your server.
+It is mostly a collection of resources, defined using certain patterns.
+
+## Format
+A recipe can be specified as a path to one of the following patterns:
+
+- JSON file
+- YAML file named with \*.yaml or \*.yml
+- ERB file named with \*.json.erb or \*.yml.erb
+- Executable to output JSON
+- Directory including recipe files recursively
+
+```
+$ serverkit apply recipe
+$ serverkit apply recipe.json
+$ serverkit apply recipe.json.erb
+$ serverkit apply recipe.json.erb --variables=variables
+$ serverkit apply recipe.json.erb --variables=variables.json
+$ serverkit apply recipe.json.erb --variables=variables.json.erb
+$ serverkit apply recipe.json.erb --variables=variables.yml
+$ serverkit apply recipe.json.erb --variables=variables.yml.erb
+$ serverkit apply recipe.json.erb --variables=variables/
+$ serverkit apply recipe.yml
+$ serverkit apply recipe.yml.erb
+$ serverkit apply recipes/
+```
+
+## Variables
+When using ERB recipe, you can also give optional variables file via `--variables=` option
+that defines configurations in a Hash object for ERB template.
+It supports similar format variation with Recipe.
+In ERB template, you can use given variables via methods named after its keys.
+
+## Handler
+When any changes are successfully applied to a resource and it has notify attribute,
+it notifies handlers that are referenced by their id.
+The notified handlers will run only once after all resources finished their applications.
+Here's an example of restarting Dock on Mac OS X when its preferences change.
+
+## Example
+```yml
+# variables.yml
+dotfiles_repository: r7kamura/dotfiles
+user: r7kamura
+```
+
+```yml
+# recipe.yml.erb
+resources:
+  - type: package
+    name: mysql
+  - type: package
+    name: redis
+  - type: git
+    repository: git@github.com:<%= dotfiles_repository %>.git
+    path: /Users/<%= user %>/src/github.com/<%= dotfiles_repository %>
+  - type: symlink
+    source: /Users/<%= user %>/.zshrc
+    destination: /Users/<%= user %>/src/github.com/<%= dotfiles_repository %>/.zshrc
+  - type: defaults
+    domain: com.apple.dock
+    key: autohide
+    value: 1
+    notify:
+      - restart_dock
+handlers:
+  - id: restart_dock
+    type: command
+    script: killall Dock
+```
+
+```
+$ serverkit apply recipe.yml.erb --variables=variables.yml
+```

data/doc/resource.md

@@ -0,0 +1,22 @@
+# Resource
+A resource is a statement of configuration policy that describes the desired state for an item.
+
+## Attributes
+Each resource has different attributes along with its type.
+By default, all types of resource can or must have the following attributes:
+
+- type - what type this resource represents (required)
+- check_script - pass shell script to override the `#check` phase
+- recheck_script - pass shell script to override the `#recheck` phase (runned after `#apply`)
+- id - change resource identifier used in log, and also used for `notify`
+- notify - specify an Array of handler ids that should be applied after changed
+
+## Example
+Here is a tiny example recipe that has only one resource with `type` and `name` attributes.
+It desceibes that there must be a mysql package in the target machine.
+
+```yml
+resources:
+  - type: package
+    name: mysql
+```

data/doc/resource_command.md

@@ -0,0 +1,18 @@
+# command
+`command` is a resource to execute a command on target hosts.
+This resource takes a shell script to be executed.
+
+## Attributes
+- script - shell script to be executed (required, type: `String`)
+
+## Example
+This recipe ensures the login shell to be `/bin/zsh` on Mac OS X.
+Note that `check_script` attribute (* this attribute is available on all resources)
+is used to check if the current login shell is configured with `/bin/zsh` by `finger` command.
+
+```yaml
+resources:
+  - type: command
+    check_script: "finger -l | grep -E 'Shell: /bin/zsh$'"
+    script: chsh -s /bin/zsh <%= ENV["USER"] %>
+```

data/doc/resource_directory.md

@@ -0,0 +1,20 @@
+# directory
+`directory` is a resource to manage a directory on file system.
+
+## Attributes
+- group - directory group (type: `String`)
+- mode - directory mode (type: `Integer`)
+- owner - directory owner (type: `String`)
+- path - directory path (required, type: `String`)
+
+## Example
+This recipe ensures a directory exists at `/home/foo/.ssh` on a remote host,
+and its mode is `700`, and it is owned by user `foo`.
+
+```yaml
+resources:
+  - type: directory
+    path: /home/foo/.ssh
+    mode: 700
+    owner: foo
+```

data/doc/resource_file.md

@@ -0,0 +1,22 @@
+# file
+`file` is a resource to manage a file on file system.
+
+## Attributes
+- content - file content (type: `String`). `remote_host` resource is recommended for complex content.
+- group - file group (type: `String`)
+- mode - file mode (type: `Integer`)
+- owner - file owner (type: `String`)
+- path - file path (required, type: `String`)
+
+## Example
+This recipe ensures a file exists at `/home/foo/.ssh/authorized_keys` on a remote host
+with specified content, and its mode is `600`, and its owner is user `foo`.
+
+```yaml
+resources:
+  - type: file
+    path: /home/foo/.ssh/authorized_keys
+    content: ...
+    mode: 600
+    owner: foo
+```

data/doc/resource_git.md

@@ -0,0 +1,20 @@
+# git
+`git` is a resource to ensure a git repository exists on a remote host.
+
+## Attributes
+- path - where repository is cloned (required, type: `String`)
+- repository - repository URL (required, type: `String`)
+- state - whether it must be same revision with origin (`"cloned"` or `"updated"`, default: `"cloned"`)
+
+## Example
+This recipe ensures a git repository is cloned from
+`https://github.com/r7kamura/dotfiles.git` at
+`/Users/r7kamura/src/github.com/r7kamura/dotfiles` on a remote host.
+
+```yaml
+resources:
+  - type: git
+    path: /Users/r7kamura/src/github.com/r7kamura/dotfiles
+    repository: https://github.com/r7kamura/dotfiles.git
+    state: updated
+```

data/doc/resource_group.md

@@ -0,0 +1,16 @@
+# group
+`group` is a resource to ensure a group exists on a remote host.
+
+## Attributes
+- gid - group gid (type: `Integer`)
+- name - group name (required, type: `String`)
+
+## Example
+This recipe ensures a group `staff` of gid `20` exists on a remote host.
+
+```yaml
+resources:
+  - type: group
+    gid: 20
+    name: staff
+```

data/doc/resource_line.md

@@ -0,0 +1,27 @@
+# line
+`line` is a resource to ensure a particular line is in a file,
+or replace an existing line using regexp.
+
+## Attributes
+- path - file path on remote host (required, type: `String`)
+- insert_after - regexp to specify where line will be inserted (type: `String`), prior last match
+- insert_before - regexp to specify where line will be inserted (type: `String`), prior last match
+- line - inserted line content (required, type: `String`)
+- pattern - regexp to check if a line already exists or not (type: `String`)
+- state - `"absent"` or `"present"` (default)
+- validation_script - shell script to run before copying into place (type: `String`, Use `%{path}` in the command to indicate the current file to validate)
+
+## Example
+This recipe ensures a line `"%wheel ALL=(ALL) ALL"` is in `/etc/sudoers` before a line
+matched with `Regexp.new("^#includedir")`, if no line matched with
+`Regexp.new('%wheel +ALL=\(ALL\) ALL')` and `visudo -cf /path/to/tempfile` succeeded.
+
+```yaml
+resources:
+  - type: line
+    path: /etc/sudoers
+    pattern: '%wheel +ALL=\(ALL\) ALL'
+    line: "%wheel ALL=(ALL) ALL"
+    insert_before: "^#includedir"
+    validation_script: visudo -cf %{path}
+```

data/doc/resource_nothing.md

@@ -0,0 +1,17 @@
+# nothing
+`nothing` is a resource to do nothing.
+This is useful for handlers to run after other resources finished,
+or useful for some debug use.
+This resource always fails on check phase and succeeds on recheck phase.
+
+## Attributes
+No specific attributes for this resource,
+but of course the default attributes are available on all resource types.
+
+## Example
+This is an example recipe to do nothing...
+
+```yaml
+resources:
+  - type: nothing
+```

data/doc/resource_package.md

@@ -0,0 +1,19 @@
+# package
+`package` is a resource to ensure a specified package is installed
+using the main package system on the target host OS (e.g. `yum`, `apt`, `homebrew`, ...).
+
+## Attributes
+- name - package name (required, type: `String`, e.g. `"nginx"`)
+- options - additional command lien options (type: `String`, e.g. `"--HEAD"`)
+- version - package version (type: `String`, some package systems don't support this)
+
+## Example
+This is an example recipe to install `mysql` and `nginx`.
+
+```yaml
+resources:
+  - type: package
+    name: mysql
+  - type: package
+    name: nginx
+```

data/doc/resource_recipe.md

@@ -0,0 +1,20 @@
+# recipe
+`recipe` is a resource to include other resources in a specified recipe.
+You can use any recipe format the same way as normal recipe,
+and of course variables are available in included recipes.
+`serverkit inspect` action, that shows fully-expanded resources,
+ might help you because nested recipes tend to become complex.
+
+## Attributes
+- path - path to an included recipe (required, type: `String`)
+
+## Example
+This is an example recipe to bundle other recipes
+
+```yaml
+resources:
+  - type: recipe
+    path: homebrew.json.erb
+  - type: recipe
+    path: dotfiles.yml
+```

data/doc/resource_remote_file.md

@@ -0,0 +1,22 @@
+# remote_file
+`remote_file` is a resource to transfer a file from a client machine to a remote machine.
+
+## Attributes
+- destination - file path on remote machine (required, type: `String`)
+- group - file group (type: `String`)
+- mode - file mode (type: `Integer`)
+- owner - file owner (type: `String`)
+- source - file path on client machine (required, type: `String`)
+
+## Example
+This recipe ensures a file exists at `/home/foo/.ssh/authorized_keys` on a remote host
+with same content with `files/authorized_keys` on a client side.
+
+```yaml
+resources:
+  - type: remote_file
+    destination: /home/foo/.ssh/authorized_keys
+    source: files/authorized_keys
+    mode: 600
+    owner: foo
+```

data/doc/resource_service.md

@@ -0,0 +1,15 @@
+# service
+`service` is a resource to manage services on remote hosts
+by OS specific init systems (e.g. BSD init, systemd, upstart, ...).
+
+## Attributes
+- name - service name (required, type: `String`)
+
+## Example
+This is an example recipe to ensure `nginx` is running.
+
+```yaml
+resources:
+  - type: service
+    name: nginx
+```

data/doc/resource_symlink.md

@@ -0,0 +1,17 @@
+# symlink
+`symlink` is a resource to ensure a symlink exists with specified source and destination.
+
+## Attributes
+- destination - symlink destination path on remote host (required, type: `String`)
+- source - symlink source path on remote host (required, type: `String`)
+
+## Example
+This is an example recipe to ensure a symlink in remote host
+from `/Users/foo/.bashrc` to `/Users/foo/dotfiles/.bashrc`.
+
+```yaml
+resources:
+  - type: symlink
+    destination: /Users/foo/dotfiles/.bashrc
+    source: /Users/foo/.bashrc
+```

data/doc/resource_template.md

@@ -0,0 +1,23 @@
+# template
+`template` is a resource to transfer a file from client host to remote host
+with expanding ERB template with given variables.
+
+## Attributes
+- destination - file path on remote machine (required, type: `String`)
+- group - file group (type: `String`)
+- mode - file mode (type: `Integer`)
+- owner - file owner (type: `String`)
+- source - file path on client machine (required, type: `String`)
+
+## Example
+This recipe ensures a file exists at `/home/foo/.ssh/authorized_keys` on remote host
+with same content with a expanded result of `files/authorized_keys.erb`.
+
+```yaml
+resources:
+  - type: remote_file
+    destination: /home/foo/.ssh/authorized_keys
+    source: files/authorized_keys.erb
+    mode: 600
+    owner: foo
+```

data/doc/resource_user.md

@@ -0,0 +1,20 @@
+# user
+`user` is a resource to ensure a user exists on remote host.
+
+## Attributes
+- gid - group gid (type: `Integer` or `String`)
+- home - path to home directory (type: `String`)
+- name - user name (required, type: `String`)
+- password - user raw password (type: `String`, will be encrypted with SHA512)
+- shell - log-in shell (type: `String`)
+- system - pass `true` to make system user (`true` or `false`, default: `false`)
+- uid - user uid (type: `Integer`)
+
+## Example
+This recipe ensures a user `foo` exists on remote host.
+
+```yaml
+resources:
+  - type: user
+    name: foo
+```

data/doc/vagrant_integration.md

@@ -0,0 +1,34 @@
+# Vagrant integration
+If you want to use serverkit with [Vagrant](https://www.vagrantup.com/),
+there are 2 options to do it.
+
+## --hosts=
+One is to use pass the machine's host name via `--hosts=` option like below.
+Note that `vagrant ssh-config` command outputs SSH configuration for the machine on vagrant
+with `Host default`, and serverkit will use it by `--hosts=default` option.
+
+```
+$ vagrant ssh-config >> ~/.ssh/config
+$ serverkit apply recipe.yml --hosts=default
+```
+
+## vagrant-serverkit
+There is a 3rd party vagrant plugin called
+[vagrant-serverkit](https://github.com/r7kamura/vagrant-serverkit).
+It helps you provision your vagrant box with using serverkit.
+
+```rb
+# Vagrantfile
+Vagrant.configure("2") do |config|
+  config.vm.box = "ubuntu/trusty64"
+  config.vm.provision(
+    :serverkit,
+    recipe_path: "recipe.yml",
+  )
+end
+```
+
+```
+$ vagrant plugin install vagrant-serverkit
+$ vagrant up
+```

data/example/recipe.yml

@@ -18,4 +18,3 @@ resources:
     line: "%wheel ALL=(ALL) ALL"
     insert_before: "^#includedir"
     validation_script: visudo -cf %{path}
-    state: absent

data/lib/serverkit/actions/validate.rb

@@ -4,7 +4,6 @@ module Serverkit
   module Actions
     class Validate < Base
       def run
-        puts "Success"
       end
     end
   end

data/lib/serverkit/command.rb

@@ -8,8 +8,13 @@ require "serverkit/errors/missing_recipe_path_argument_error"
 require "serverkit/errors/unknown_action_name_error"
 
 module Serverkit
-  # Command clsas takes care of command line interface.
-  # It builds and runs an Action object from given command line arguements.
+  # This class is responsible for command line interface.
+  # An instance of this class builds an instance of Actions::Base class,
+  # then calls its `#call` method, and it exits with exit status 0 unless any error found.
+  # This class should be used only from bin/serverkit executable.
+  # If you need to use serverkit's any feature from Ruby code,
+  # use a child of Actions::Base class instead because
+  # this class only focuses on command line interface.
   class Command
     LOG_LEVELS_TABLE = {
       "" => Logger::INFO,

data/lib/serverkit/resources/base.rb

@@ -167,7 +167,7 @@ module Serverkit
         run_command("mktemp -u 2>/dev/null || mktemp -u -t tmp").stdout.rstrip
       end
 
-      # @note "metadata" meens a set of group, mode, and owner
+      # @note "metadata" means a set of group, mode, and owner
       # @param [String] destination
       # @param [String] source
       def move_remote_file_keeping_destination_metadata(source, destination)

data/lib/serverkit/resources/git.rb

@@ -7,7 +7,7 @@ module Serverkit
 
       attribute :path, required: true, type: String
       attribute :repository, required: true, type: String
-      attribute :state, default: DEFAULT_STATE, type: String
+      attribute :state, default: DEFAULT_STATE, inclusion: %w[cloned updated], type: String
 
       # @note Override
       def apply

data/lib/serverkit/resources/group.rb

@@ -3,8 +3,8 @@ require "serverkit/resources/base"
 module Serverkit
   module Resources
     class Group < Base
-      attribute :name, required: true, type: String
       attribute :gid, type: Integer
+      attribute :name, required: true, type: String
 
       # @note Override
       def apply

data/lib/serverkit/resources/line.rb

@@ -44,14 +44,14 @@ module Serverkit
       def applied_remote_file_content
         case
         when absent?
-          content.delete(line).to_s
+          content.delete(line)
         when insert_after
-          content.insert_after(Regexp.new(insert_after), line).to_s
+          content.insert_after(Regexp.new(insert_after), line)
         when insert_before
-          content.insert_before(Regexp.new(insert_before), line).to_s
+          content.insert_before(Regexp.new(insert_before), line)
         else
-          content.append(line).to_s
-        end
+          content.append(line)
+        end.to_s
       end
 
       # @return [Serverkit::Resources::Line::Content]

data/lib/serverkit/resources/user.rb

@@ -60,8 +60,11 @@ module Serverkit
         )
       end
 
+      # @return [String, nil]
       def encrypted_password
-        @encrypted_password ||= UnixCrypt::SHA512.build(password)
+        unless password.nil?
+          @encrypted_password ||= UnixCrypt::SHA512.build(password)
+        end
       end
 
       def get_remote_encrypted_password

data/lib/serverkit/version.rb

@@ -1,3 +1,3 @@
 module Serverkit
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

data/serverkit.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.version               = Serverkit::VERSION
   spec.authors               = ["Ryo Nakamura"]
   spec.email                 = ["r7kamura@gmail.com"]
-  spec.summary               = "Configuration management toolkit for IT automation."
+  spec.summary               = "Assemble servers from your recipe."
   spec.homepage              = "https://github.com/r7kamura/serverkit"
   spec.license               = "MIT"
   spec.files                 = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serverkit
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Ryo Nakamura
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-23 00:00:00.000000000 Z
+date: 2015-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -211,9 +211,35 @@ files:
 - Rakefile
 - Vagrantfile
 - bin/serverkit
+- doc/action_apply.md
+- doc/action_check.md
+- doc/action_inspect.md
+- doc/action_validate.md
+- doc/install.md
+- doc/plug_in.md
+- doc/recipe.md
+- doc/resource.md
+- doc/resource_command.md
+- doc/resource_directory.md
+- doc/resource_file.md
+- doc/resource_git.md
+- doc/resource_group.md
+- doc/resource_line.md
+- doc/resource_nothing.md
+- doc/resource_package.md
+- doc/resource_recipe.md
+- doc/resource_remote_file.md
+- doc/resource_service.md
+- doc/resource_symlink.md
+- doc/resource_template.md
+- doc/resource_user.md
+- doc/vagrant_integration.md
 - example/recipe.yml
 - example/template.erb
 - example/variables.yml
+- images/server-colored.png
+- images/server-small.png
+- images/server.png
 - lib/readable_validator.rb
 - lib/regexp_validator.rb
 - lib/required_validator.rb
@@ -288,6 +314,6 @@ rubyforge_project:
 rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
-summary: Configuration management toolkit for IT automation.
+summary: Assemble servers from your recipe.
 test_files: []
 has_rdoc: