From 7a63de488c0fe295e4e1b8f0b3ddb344bfde66dc Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Fri, 17 May 2013 01:09:23 -0400 Subject: Update README --- README.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 README.md (limited to 'README.md') 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 +``` -- cgit v1.2.1