WIKI.md in cucumber-chef-3.0.3 vs WIKI.md in cucumber-chef-3.0.4
- old
+ new
@@ -1,7 +1,7 @@
-[](http://travis-ci.org/jovelabs/cucumber-chef)
-[](https://gemnasium.com/jovelabs/cucumber-chef)
+[](http://travis-ci.org/zpatten/cucumber-chef)
+[](https://gemnasium.com/zpatten/cucumber-chef)
I was not particularly happy with the state of the 2.x documents and considering workflow changes, etc it made sense to me to start over with the documentation. Since most things are the same the 2.x documentation will remain available in the repo as `WIKI.2.x.md`. This is WIP.
# Cucumber-Chef 3.x Documentation
@@ -18,31 +18,58 @@
Your Chef-Repo should be setup in a manner as follows:
* Use something like RVM for your ruby with your chef-repo
* Use something like bundler for your rubygems with your chef-repo
-* Use something like berkshelf for your chef cookbooks with your chef-repo
+* Use something like librarian-chef or berkshelf for your chef cookbooks with your chef-repo
If you do not use these patterns you will have an unplesant time in general.
+You also need the latest versions of:
+
+* VirtualBox (https://www.virtualbox.org/)
+* Vagrant (http://www.vagrantup.com/)
+
When using Cucumber-Chef, especially at first, I highly recommend you tail the log. Open another terminal, naviagate to your Chef-Repo root directory and run `tail -f .cucumber-chef/cucumber-chef.log`. You'll have a much better idea what's going on in the background this way, especially during bootstrapping and provisioning. And root causes of issues that are not so obvious on the console will hopefully be very obvious in the log.
# Workflow
1. `cucumber`/`rspec` is executed; cucumber-chef is called
2. `cucumber-chef` (re)creates the ecosystem from the `Labfile` (optionally executed)
3. `cucumber-chef` runs the chef-client across the ecosystem using attributes from the `Labfile` (optionally executed)
4. `cucumber`/`rspec` resumes execution
+# First-Time Execution
+
+1. Ensure you have the latest vagrant and virtualbox installed.
+2. `cucumber-chef init` to initalize a disabled config template.
+3. `cucumber-chef create test` to create a blank test feature.
+4. `cucumber-chef setup` is executed to ensure your test lab is provisioned.
+5. `cucumber` to execute features located in your `chef-repo`.
+
+# Other Execution Examples
+
+For example when I am testing, I often use this command sequence (I use binstubs, so everything will be prefixed with bin/):
+
+ echo "yes" | bin/cucumber-chef destroy && bin/cucumber-chef setup && bin/cucumber
+
+This will destroy the current test lab (if one exists), setup a new test (since we destroyed any existing labs), then execute the cucumber features.
+
+To force destruction of the containers when running cucumber place `PURGE=1` before your cucumber command like so:
+
+ PURGE=1 bin/cucumber
+
# Configuration
Cucumber-Chef creates a home directory for itself named `.cucumber-chef` off the root of your Chef-Repo. Here you can find the configuration files as well as logs and artifacts from test runs. There are two main configuration files for Cucumber-Chef. The `Labfile` in the Chef-Repo directory and `config.rb` in the Cucumber-Chef home directory.
## `Labfile`
When doing integration testing it makes sense that one generally wants to test across an entire ecosystem of servers. You typically acquire a set of virtual or bare metal servers, provision those servers acordingly, put them into play then rinse and repeat. I introduce the `Labfile`, the concept is simple if you haven't already guessed it. You define a set of servers, i.e. an ecosystem, also dictating the settings and configuration. Part of this change is because a) it makes alot of sense to me and b) it greatly decreases runtimes. Also in cucumber-chef 2.x, we had insane background sections which bothered me tremendously and this change cleans up all of that mess as well. The ultimate goal is to support configuration of multiple ecosystems, but we've got other ground to cover first so that feature will have to wait for a bit. The `Labfile` should reside in the root of your Chef-Repo.
+https://github.com/zpatten/cc-chef-repo/blob/master/Labfile
+
Here is a sample of what a `Labfile` might look like:
#!/usr/bin/env ruby
#^syntax detection
@@ -105,9 +132,125 @@
end
end
## `config.rb`
+
+https://github.com/zpatten/cc-chef-repo/blob/master/.cucumber-chef/config.rb
+
+You can customize your configuration by editing your `<chef-repo>/.cucumber-chef/config.rb` file. Here's an example of the current one I'm using for testing:
+
+ provider :vagrant
+
+ vagrant.merge!( :identity_file => "#{ENV['HOME']}/.vagrant.d/insecure_private_key",
+ :ssh => {
+ :lab_ip => "192.168.33.10",
+ :lab_port => 22,
+ :lxc_port => 22
+ },
+ :cpus => 4,
+ :memory => 4096 )
+
+ aws.merge!( :identity_file => ENV['AWS_IDENTITY'],
+ :ssh => {
+ :lab_port => 22,
+ :lxc_port => 22
+ },
+ :aws_access_key_id => ENV['AWS_ACCESS_KEY_ID'],
+ :aws_secret_access_key => ENV['AWS_SECRET_ACCESS_KEY'],
+ :aws_ssh_key_id => ENV['AWS_SSH_KEY_ID'],
+ :region => "us-west-2",
+ :availability_zone => "us-west-2a",
+ :aws_instance_arch => "i386",
+ :aws_instance_type => "c1.medium" )
+
+ artifacts ({ "chef-client-log" => "/var/log/chef/client.log",
+ "chef-client-stacktrace" => "/var/chef/cache/chef-stacktrace.out" })
+
+ chef.merge!( :version => "10.24.0",
+ :container_version => "10.18.2",
+ :cookbook_paths => %w(cookbooks site-cookbooks))
+
+ # chef.merge!( :version => "10.24.0")
+ # chef.merge!( :version => "11.4.0")
+ # chef.merge!( :version => "latest")
+
+If you want to see how your cucumber-chef installation is configured run `cucumber-chef displayconfig`:
+
+ $ cucumber-chef displayconfig
+ cucumber-chef v3.0.3
+ --------------------------------------------------------------------------------
+ ---
+ :mode: :user
+ :prerelease: false
+ :user: zpatten
+ :artifacts:
+ chef-client-log: /var/log/chef/client.log
+ chef-client-stacktrace: /var/chef/cache/chef-stacktrace.out
+ :chef:
+ :version: 10.24.0
+ :container_version: 10.18.2
+ :default_password: p@ssw0rd1
+ :render_client_rb: true
+ :cookbook_paths:
+ - cookbooks
+ - site-cookbooks
+ :test_lab:
+ :hostname: cucumber-chef
+ :tld: test-lab
+ :command_timeout: 1800
+ :provider: :vagrant
+ :aws:
+ :bootstrap_user: ubuntu
+ :lab_user: cucumber-chef
+ :lxc_user: root
+ :ssh:
+ :lab_port: 22
+ :lxc_port: 22
+ :ubuntu_release: precise
+ :aws_instance_arch: i386
+ :aws_instance_disk_store: ebs
+ :aws_instance_type: c1.medium
+ :aws_security_group: cucumber-chef
+ :identity_file:
+ :aws_access_key_id:
+ :aws_secret_access_key:
+ :aws_ssh_key_id:
+ :region: us-west-2
+ :availability_zone: us-west-2a
+ :vagrant:
+ :bootstrap_user: vagrant
+ :lab_user: cucumber-chef
+ :lxc_user: root
+ :ssh:
+ :lab_ip: 192.168.33.10
+ :lab_port: 22
+ :lxc_port: 22
+ :cpus: 4
+ :memory: 4096
+ :identity_file: /home/zpatten/.vagrant.d/insecure_private_key
+
+ --------------------------------------------------------------------------------
+ root_dir = "/home/zpatten/code/cc-chef-repo/vendor/checkouts/cucumber-chef"
+ home_dir = "/home/zpatten/code/cc-chef-repo/.cucumber-chef"
+ log_file = "/home/zpatten/code/cc-chef-repo/.cucumber-chef/cucumber-chef.log"
+ artifacts_dir = "/home/zpatten/code/cc-chef-repo/.cucumber-chef/vagrant/artifacts"
+ config_rb = "/home/zpatten/code/cc-chef-repo/.cucumber-chef/config.rb"
+ labfile = "/home/zpatten/code/cc-chef-repo/Labfile"
+ chef_repo = "/home/zpatten/code/cc-chef-repo"
+ chef_user = "zpatten"
+ chef_identity = "/home/zpatten/code/cc-chef-repo/.cucumber-chef/vagrant/zpatten.pem"
+ bootstrap_user = "vagrant"
+ bootstrap_user_home_dir = "/home/vagrant"
+ bootstrap_identity = "/home/zpatten/.vagrant.d/insecure_private_key"
+ lab_user = "cucumber-chef"
+ lab_user_home_dir = "/home/cucumber-chef"
+ lab_identity = "/home/zpatten/code/cc-chef-repo/.cucumber-chef/vagrant/id_rsa-cucumber-chef"
+ lxc_user = "root"
+ lxc_user_home_dir = "/root"
+ lxc_identity = "/home/zpatten/code/cc-chef-repo/.cucumber-chef/vagrant/id_rsa-root"
+ chef_pre_11 = true
+ --------------------------------------------------------------------------------
# Cucumber-Chef Tasks
All tasks should function in a similar manner across all providers.