diff options
author | Seth Vargo <sethvargo@gmail.com> | 2013-05-17 01:09:23 -0400 |
---|---|---|
committer | Seth Vargo <sethvargo@gmail.com> | 2013-05-19 18:09:04 -0500 |
commit | 7a63de488c0fe295e4e1b8f0b3ddb344bfde66dc (patch) | |
tree | b5dd1803d2f93c7081b915b93b8fbf0d5b9e69b9 | |
parent | 4320203e961bdde6c1f19112dd8af4b7d66c9256 (diff) | |
download | chef-zero-7a63de488c0fe295e4e1b8f0b3ddb344bfde66dc.tar.gz |
Update README
-rw-r--r-- | README.md | 145 | ||||
-rw-r--r-- | README.rdoc | 79 |
2 files changed, 145 insertions, 79 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..f8102c3 --- /dev/null +++ b/README.md @@ -0,0 +1,145 @@ +Chef Zero +========= + +Description +----------- +Chef Zero is a simple, easy-install, in-memory Chef server that can be useful +for Chef Client testing and chef-solo-like tasks that require a full Chef +Cerver. It IS intended to be simple, Chef 11 compliant, easy to run and fast +to start. It is NOT intended to be secure, scalable, performant or persistent. +It does NO input validation, authentication or authorization (it will not +throw a 400, 401 or 403). It does not save data, and will start up empty each +time you start it. + +Because Chef Zero runs in memory, it's super fast and lightweight. This makes +it perfect for testing against a "real" Chef Server without mocking the +entire Internet. + + +Installation +------------ +This server can be installed as a Ruby Gem. + + $ gem install chef-zero + +If you're using bundler, add `chef-zero` as a development dependency: + +```ruby +group :development do + gem 'chef-zero' +end +``` + +Or in a `.gemspec` + +```ruby +s.add_development_dependency 'chef-zero' +``` + +You can also clone the source repository and install it using `rake install`. + +Usage +----- +One of chef-zero's primary uses is as a small test server for people writing and +testing clients. Here's a simple example of starting it up: + +```ruby +require 'chef_zero/server' +server = ChefZero::Server.new(port: 4000) +server.start +``` + +This will create a server instance in the foreground. To stop the server: + +```ruby +server.stop +``` + +This is great for debugging and logging requests, but you'll probably want +to run this in the background so you have full control of your thread. + +To run Chef Zero in the background, simply issue the `start_background` command: + +```ruby +require 'chef_zero/server' +server = ChefZero::Server.new(port: 4000) +server.start_background +``` + +You can stop the server the same way: + +```ruby +server.stop +``` + +### Valid Options +You may currently pass the following options to the initializer: + +- `host` - the host to run on (Default: '127.0.0.1') +- `port` - the port to run on (Default: 8889) +- `debug` - run in debug mode to see all requests and responses (Default: false) + + +CLI (Comand Line) +----------------- +If you don't want to use Chef Zero as a library, you can simply start an instance +with the included `chef-zero` executable: + + $ chef-zero + +Note, this will run in the foreground. + +You now have a fully functional (empty) Chef Server running. + +To try it out, go into the `chef-zero/playground` directory and run `knife`. It +will behave the same as a normal Chef Server, and all normal knife commands will +work (show, list, delete, from file, upload, download, diff ...). For example, +with +knife-essentials+ (or Chef 11) you can upload everything in the repo: + + chef-zero/playground> knife upload . + Created remote/cookbooks/blah + Created remote/cookbooks/blork + Created remote/data_bags/foo/ + Created remote/data_bags/foo/bar.json + Created remote/data_bags/foo/baz.json + Created remote/data_bags/foo/blarghle.json + Created remote/data_bags/foom/ + Created remote/data_bags/foom/x.json + Created remote/data_bags/widdle/ + Created remote/data_bags/widdle/blank.json + Created remote/data_bags/widdle/wow.json + Created remote/environments/desert.json + Created remote/environments/rainforest.json + Created remote/environments/semi_arid_plains.json + + chef-zero/playground> knife environment list + _default + desert + rainforest + semi_arid_plains + +To use it in your own repository, create a `knife.rb` like so: + + chef_server_url 'http://127.0.0.1:8889' + node_name 'stickywicket' + client_key 'path_to_any_pem_file.pem' + +And use knife like you normally would. + +Since Chef Zero does no authentication, any `.pem` file will do. The client just +needs something to sign requests with (which will be ignored on the server). Even +though it's ignored, the `.pem` must still be a valid format. + +Now, stop the Chef Zero server and all the data is gone! + +Run `chef-zero --help` to see a list of the supported flags and options: + +```text +Usage: chef-zero [ARGS] + -H, --host HOST Host to bind to (default: 127.0.0.1) + -p, --port PORT Port to listen on + --[no-]generate-keys Whether to generate actual keys or fake it (faster). Default: false. + -d, --debug Show requests and debugging output + -h, --help Show this message + --version Show version +``` diff --git a/README.rdoc b/README.rdoc deleted file mode 100644 index 1c00dcb..0000000 --- a/README.rdoc +++ /dev/null @@ -1,79 +0,0 @@ -== Chef Zero - -= DESCRIPTION: - -chef-zero is a simple, easy-install, in-memory Chef server that can be useful -for Chef client testing and chef-solo-like tasks that require a full Chef -server. It IS intended to be simple, Chef 11 compliant, easy to run and fast -to start. It is NOT intended to be secure, scalable, performant or persistent. -It does NO input validation, authentication or authorization (it will not -throw a 400, 401 or 403). It does not save data, and will start up empty each -time you start it. - -= INSTALLATION: - -This server can be installed as a Ruby Gem. - - gem install chef-zero - -You can also copy the source repository and install it using +rake install+. - -= TEST SERVER USAGE: - -One of chef-zero's primary uses is as a small test server for people writing and -testing clients. To bring it up, simply do: - - require 'chef_zero/server' - server = ChefZero::Server.new(:port => 8889) - server.start - -To bring it up in the background, do: - - thread = Thread.new { server.start } - -To kill the background server, do: - - thread.stop - -= COMMAND LINE USAGE: - -To simply run the server, you can just type +chef-zero+ after installing and you -will have a fully functional (empty) Chef Server running. - -To try it out, go into the +chef-zero/playground+ directory and run knife. It -will behave the same as a normal Chef server, and all normal knife commands will -work (show, list, delete, from file, upload, download, diff ...). For example, -with +knife-essentials+ (or Chef 11) you can upload everything in the repo: - - chef-zero/playground> knife upload . - Created remote/cookbooks/blah - Created remote/cookbooks/blork - Created remote/data_bags/foo/ - Created remote/data_bags/foo/bar.json - Created remote/data_bags/foo/baz.json - Created remote/data_bags/foo/blarghle.json - Created remote/data_bags/foom/ - Created remote/data_bags/foom/x.json - Created remote/data_bags/widdle/ - Created remote/data_bags/widdle/blank.json - Created remote/data_bags/widdle/wow.json - Created remote/environments/desert.json - Created remote/environments/rainforest.json - Created remote/environments/semi_arid_plains.json - - chef-zero/playground> knife environment list - _default - desert - rainforest - semi_arid_plains - -To use it in your own repository, create a +knife.rb+ like so: - - chef_server_url "http://127.0.0.1:8889" - node_name "stickywicket" - client_key "path_to_any_pem_file.pem" - -And use knife like you normally would. - -Since Chef Zero does no authentication, any .pem file will do. The client just -needs something to sign requests with (which will be ignored on the server). |