Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Restructure the README #50

Merged
merged 5 commits into from
Apr 28, 2017
Merged

Restructure the README #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2d59fd3
restructure the README
tknerr Apr 28, 2017
dd68c08
separate headers for main tools vs tweaks and plugins
tknerr Apr 28, 2017
bf12eaa
wording updates and refer to CHANGELOG for specific tool versions
tknerr Apr 28, 2017
684f980
add CHANGELOG entry
tknerr Apr 28, 2017
3559697
point to the github releases page for downloading the vm image
tknerr Apr 28, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ Improvements:
* add `--provision-only` flag to the `update-vm.sh` script (see [PR #42](https://github.com/tknerr/linus-kitchen/pull/42), [PR #47](https://github.com/tknerr/linus-kitchen/pull/47))
* configure PS1 to provide a usable shell prompt for Git (see [PR #45](https://github.com/tknerr/linus-kitchen/pull/45))
* tweak Atom to scale the tree view's font size along with the editor (see [PR #49](https://github.com/tknerr/linus-kitchen/pull/49))
* restructure the README to better differentiate between Usage and Development (see [PR #50](https://github.com/tknerr/linus-kitchen/pull/50))

Breaking changes:

Expand Down
197 changes: 113 additions & 84 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,70 +9,29 @@ An Ubuntu Desktop 16.04 based development box for Infrastructure-as-Code develop

Yes, it is being set up with Vagrant and Chef, so it's a bit meta... It is also the Linux based equivalent of the [Bill's Kitchen](https://github.com/tknerr/bills-kitchen) DevPack.

## Prerequisites

You only need [VirtualBox](http://virtualbox.org/wiki/Downloads) and [Vagrant](http://www.vagrantup.com/)
installed.

All other requirements, along with ChefDK and Git will be installed *inside the Vagrant VM* during provisioning, i.e. you don't need them installed on your host machine.

## Basic Usage

Bring up the linus-kitchen VM:
```
$ vagrant up
```

This will take a while, as it will do quite a few things inside the VM:

1. Setup a new user account ('user') under which the VM will be provisioned
1. Download and install [Git](https://git-scm.org/) and [ChefDK](https://downloads.chef.io/chef-dk/)
1. Copy the current directory into the VM (will be placed in `~/vm-setup`)
1. Install cookbook dependencies via [Berkshelf](http://berkshelf.com/) to `~/vm-setup/cookbooks/vm/cookbooks`
1. Trigger a [Chef-Zero](https://www.chef.io/blog/2013/10/31/chef-client-z-from-zero-to-chef-in-8-5-seconds/) run to apply the `~/vm-setup/cookbooks/vm/recipes` to the VM (see "What's included?")
1. Verify the installation using a battery of [Serverspec](http://serverspec.org/) tests

Watch the vagrant output on the console for seeing progress. At the end you
should see all tests passing:

```
...
==> default:
==> default: update-vm.sh
==> default: installs git
==> default: installs chefdk 1.3.32
==> default:
==> default: Finished in 24.44 seconds (files took 0.81272 seconds to load)
==> default: 33 examples, 0 failures
...
```

You can now log in to the Desktop (the VM is started in GUI mode):

* user: "user"
* password: "user"

Once logged in, you can open a terminal and you will have all of the tools available (see next section).

## What's included?

These are the main tools included in Linus' Kitchen:
### Main tools

These are the main tools included in Linus' Kitchen (see CHANGELOG for the specific versions):

* [Git](https://git-scm.org/)
* [ChefDK](https://downloads.chef.io/chef-dk/)
* [Vagrant](http://vagrantup.com/)
* [Packer](http://packer.io/)
* [VirtualBox](https://www.virtualbox.org/)
* [Docker](http://docker.io/)
* [Atom Editor](http://terraform.io/)
* [Atom Editor](http://atom.io/)

### Tweaks and Plugins

Other tweaks worth mentioning:

* Scripts in `~/.bash.d/*.sh` are sourced from `~/.bashrc`, pre-configured with the following:
* set up `be` as an alias for `bundle exec`
* run `chef shell-init bash` for initializing the ChefDK
* configure "virtualbox" as the `$VAGRANT_DEFAULT_PROVIDER`
* configure a usable `PS1` shell prompt for Git
* sets up `be` as an alias for `bundle exec`
* runs `chef shell-init bash` for initializing the ChefDK
* configures "virtualbox" as the `$VAGRANT_DEFAULT_PROVIDER`
* configures a usable `PS1` shell prompt for Git
* Bundler is configured for parallel downloading and retrying (see `~/.bundle/config`)
* Customized Atom config, e.g. with SublimeText-like tab behaviour (see `~/.atom/config.cson`)
* Customized `~/.vagrant.d/Vagrantfile` and `~/.kitchen/config.yml` for caching as much as possible
Expand All @@ -89,20 +48,93 @@ Other tweaks worth mentioning:
* [language-chef](https://atom.io/packages/language-chef) - code snippets for Chef recipes
* Symlinked [`update-vm.sh`](scripts/update-vm.sh) to `/usr/local/bin/update-vm` so it's in the `$PATH` and can be used for updating the VM from the inside (see below)

## Updating Linus' Kitchen

Even though you can trigger an update from outside the VM via `vagrant provision`,
you usually want to do that from *inside the VM* as this is your current working environment.
The update is done via Chef so it should be fully idempotent.
## Usage

### Obtaining and Starting the VM Image

The latest version of the Linus Kitchen can be downloaded as a VM image from here:

* https://github.com/tknerr/linus-kitchen/releases

After downloading the .ova file you can import it into VMWare Fusion / Workstation Player via `File -> Import...`.
Once imported, you can simply start the VM and log in:

* username: "user"
* password: "user"

From then on just open a terminal and you will have all of the tools available (see "What's included?").

### Updating the VM

You can run these commands from anywhere inside the VM:

* `update-vm` - to provision the VM (applies the Chef recipes from the local linus-kitchen repo at `~/vm-setup`)
* `update-vm --pull` - same as above, but pull the latest changes from the remote linus-kitchen repo before
* `update-vm --verify-only` - don't provision the VM, only run the Serverspec tests
* `update-vm --provision-only` - provision the VM, but don't run the Serverspec tests
* `update-vm` - update the VM by applying the Chef recipes from the locally checked out repo at `~/vm-setup`
* `update-vm --pull` - same as above, but update repo before by pulling the latest changes
* `update-vm --verify-only` - don't update the VM, only run the Serverspec tests
* `update-vm --provision-only` - don't run the Serverspec tests, only update the vm

### Keyboard Layout and Locale Settings

The VM ships with a full `US` keyboard layout and `en_US.UTF-8` locale by default.

To change the keyboard layout to your preferred language use `System Settings... -> Text Entry` in the VM.

If you have a totally different keymap (e.g. on a MacBook) you can always reconfigure it:
```
sudo dpkg-reconfigure keyboard-configuration
```

If want to reconfigure the locale:
```
sudo dpkg-reconfigure locales
```

## Development

### Prerequisites

You need [VMware Workstation Pro](https://www.vmware.com/products/workstation.html) / [VMware Fusion Pro](https://www.vmware.com/products/workstation.html) and [Vagrant](http://www.vagrantup.com/) with the [vagrant-vmware-plugin](https://www.vagrantup.com/vmware/) installed.

If you don't mind about running 64-bit VirtualBox VMs inside Linus Kitchen, you only even need [VirtualBox](http://virtualbox.org/wiki/Downloads) and [Vagrant](http://www.vagrantup.com/) installed (note that VirtualBox only supports nested 32-bit guests).

All other requirements, along with ChefDK and Git will be installed *inside the Vagrant VM* during provisioning, i.e. you don't need them installed on your host machine.

### Basic Development Workflow

Bring up the developer VM:
```
$ vagrant up
```

This will take a while, as it will do quite a few things inside the VM:

## Acceptance Test
1. Setup a new user account ('user') under which the VM will be provisioned
1. Download and install [Git](https://git-scm.org/) and [ChefDK](https://downloads.chef.io/chef-dk/)
1. Copy the current directory into the VM (will be placed in `~/vm-setup`)
1. Install cookbook dependencies via [Berkshelf](http://berkshelf.com/) to `~/vm-setup/cookbooks/vm/cookbooks`
1. Trigger a [Chef-Zero](https://www.chef.io/blog/2013/10/31/chef-client-z-from-zero-to-chef-in-8-5-seconds/) run to apply the `~/vm-setup/cookbooks/vm/recipes` to the VM (see "What's included?")
1. Verify the installation using a battery of [Serverspec](http://serverspec.org/) tests

Watch the vagrant output on the console for seeing progress. At the end you
should see all tests passing:

```
...
==> default:
==> default: update-vm.sh
==> default: installs git
==> default: installs chefdk 1.3.32
==> default:
==> default: Finished in 26.85 seconds (files took 1.08 seconds to load)
==> default: 48 examples, 0 failures
...
```

If these are passing as expected, you can continue developing on the Chef recipes within this repo.
Please don't forget to add a test for each new feature you add (see "Contributing")

### Running the Acceptance Tests

In addition to the Serverspec tests (which verify that the installed tools are properly
configured and working as expected) you can also execute a minimal acceptance test which covers the [common usage scenarios](https://github.com/tknerr/vagrant-workflow-tests/blob/master/spec/acceptance/usage_scenarios_spec.rb) when developing with Vagrant and Chef, including:
Expand All @@ -120,62 +152,59 @@ $ rspec

If all goes well you should see an output [like this](https://cloud.githubusercontent.com/assets/365744/3607278/0579cae2-0d45-11e4-81f0-9236c592562a.png).

## Keyboard Layout

Seems to be too hard to automate for me, so you have to do this manually for now:
```
sudo dpkg-reconfigure keyboard-configuration
```

## Packaging
### Packaging

Whenever you feel like distributing a fat VM image rather than a Vagrantfile,
you can package / export it as a VirtualBox image. This might be useful
you can package / export it as a VirtualBox / VMware image. This might be useful
for distributing the initial version of the developer VM to your dev team,
or simply for preserving checkpoint releases as a binary images.

First, start from a clean state, and make sure vagrant-cachier is disabled:
Let's start from a clean state:
```
$ vagrant destroy -f
$ export VAGRANT_NO_PLUGINS=1
$ vagrant up
```

Next, unmount the /vagrant shared folder (will be restored on next `vagrant up`):
```
$ vagrant ssh -c "sudo umount /vagrant"
```
This will provision the VM as usual. Once the provisioning succeeded, we will
do a few cleanup steps before packaging the VM.

Also, you may want to clean out the VM for a minimal export image:
First, unmount the /vagrant shared folder:
```
$ vagrant ssh -c "wget -qO- https://raw.githubusercontent.com/boxcutter/ubuntu/master/script/cleanup.sh | sudo bash"
$ vagrant ssh -c "sudo umount /vagrant -f"
```

Then remove the vagrant user account:

```
$ vagrant ssh -c "sudo pkill -KILL -u vagrant"
$ vagrant ssh -c "sudo userdel -f -r vagrant"
```

Finally, shutdown the VM, remove the sharedfolder, and export the VM as an .ova file:

For VirtualBox:
```
$ vagrant halt
$ VBoxManage sharedfolder remove "Linus Kitchen" --name "vagrant"
$ VBoxManage modifyvm "Linus Kitchen" --name "Linus Kitchen v0.1"
$ VBoxManage export "Linus Kitchen v0.1" --output "linus-kitchen-v0.1.ova" --options manifest,nomacs
$ VBoxManage modifyvm "Linus Kitchen" --name "Linus Kitchen v0.1.0"
$ VBoxManage export "Linus Kitchen v0.1.0" --output "linus-kitchen-v0.1.0_virtualbox.ova" --options manifest,nomacs
```

For VMware:
```
$ vagrant halt
$ VMX_FILE=`cat .vagrant/machines/default/vmware_fusion/id`
$ ovftool --name="Linus Kitchen v0.1.0" "VMX_FILE" linus-kitchen-v0.1.0_vmware.ova
```

Don't forget to throw away the VM enable vagrant-cachier again:
Don't forget to throw away the VM when you are done:
```
$ vagrant destroy -f
$ unset VAGRANT_NO_PLUGINS
```

## Contributing

1. Fork the repository on Github
1. Create a named feature branch (like `add-xyz`)
1. Create a named feature branch (like `feature/add-xyz`)
1. Implement your changes, add tests
1. Commit and push
1. Submit a Pull Request using Github
1. Submit a Pull Request via Github