veewee-atlassian 0.3.11

data/doc/definition.md

@@ -0,0 +1,165 @@
+# Veewee definitions
+
+Veewee uses `definitions` to create new boxes. Every definition is based on a `template`.
+
+A `template is represented by a sub-directory in the folder `templates`.
+
+There you'll find all the templates you can use.
+
+Each folder name follows a naming scheme to help you choosing the right template:
+
+    <OS name>-<version>-<architecture>[-<install flavor>]
+
+The template for a Ubuntu 12.10 server (i386) basebox looks like this:
+
+    ubuntu-12.10-server-i386[-netboot]
+                             ^ ----- install flavor
+                        ^ ----- architecture
+           ^ ----- version
+    ^ ----- OS name
+
+
+## List existing definitions
+
+To list all available definitions run this command:
+
+    veewee vbox list
+
+
+## Listing available templates
+
+Veewee provides templates for a lot of different Operation Systems.
+
+To see all the templates provided:
+
+    $ veewee vbox templates
+
+Templates have the same structure as a <definition> but are provided by veewee as templates for definitions.
+
+Definitions are *your* box templates.
+
+
+## Creating a definition
+
+A definition is created by 'cloning' a *template* into the `definitions` folder.
+
+To create a definition you use the `define` subcommand:
+
+    veewee vbox define 'myubuntubox' 'ubuntu-12.10-server-amd64'
+
+If you want to use an external repo for the definition you can specify a git-url
+
+    veewee vbox define 'myubuntubox' 'git://github.com/jedi4ever/myubuntubox'
+
+
+## Remove a definition
+
+If you change your mind and want to get rid of a definition simply call this command:
+
+    veewee vbox undefine 'myubuntubox'
+
+Or you can remove the folder under `definitions`:
+
+    rm -r ./definitions/myubuntubox
+
+
+## Example
+
+Let's say you'd like to have a *Ubuntu 12.10 server (i386)* basebox.
+
+Go and find the template `ubuntu-12.10-server-i386` within `templates` to verify you can create a definition.
+
+Use the `veewee vbox define` command to create your definition with a custom name.
+
+	IMPORTANT: You should avoid dots in the name because the boxname gets used as the hostname also.
+	Dots in the boxname currently lead to invalid hostnames which causes several sideeffects eg. preventing the network devices to start.
+
+The following command copies the folder `templates/ubuntu-12.10-server-i386` to `definitions/myubuntubox`:
+
+    $ veewee vbox define 'myubuntubox' 'ubuntu-12.10-server-i386'
+    The basebox 'myubuntubox' has been successfully created from the template 'ubuntu-12.10-server-i386'
+    You can now edit the definition files stored in definitions/myubuntubox or build the box with:
+    veewee vbox build 'myubuntubox'
+
+Verify that all files are in place:
+
+    $ ls definitions/myubuntubox
+    definition.rb  postinstall.sh preseed.cfg
+
+You now can inspect and modify the defaults to your needs (see below) or start building the box with this command:
+
+    veewee vbox build 'myubuntubox'
+
+Veewee now asks for downloading the ISO and will start his magic.
+
+
+## Modify the definition (optional)
+
+You can tweak and customize every detail of the box by modifying and extending the (sane) default settings
+that come with a template.
+
+If you want to modify these settings take a look at [customization instructions](customize.md).
+
+
+## Getting the CD-ROM file in place
+
+The [CD-ROM file](http://en.wikipedia.org/wiki/ISO_image) (also called `.iso` or *disk image* file)
+provides all files needed to install the OS.
+
+This file is essential for starting the installation process.
+
+If you already have an `.iso` file for the desired distribution on your disk put it inside the `./iso` directory.
+
+Create this directory if it does not exist. Otherwise Veewee will ask you to download the ISO file from the web.
+
+Depending on your internet connection fetching a ISO file can take several minutes.
+
+
+## Build the new box:
+
+In order to build the box execute this command:
+
+    $ veewee vbox build 'myubuntubox'
+
+TIPP: If you already built a box with that name you can use `--force` to overwrite an existing installation.
+
+The command will run the following routines behind the scenes:
+
+- It will create a machine + disk according to the `definition.rb`
+- Note: `:os_type_id` = The internal Name Virtualbox uses for that Distribution
+- Mount the ISO File `:iso_file`
+- Boot up the machine and wait for `:boot_time`
+- Send the keystrokes in `:boot_cmd_sequence`
+- Startup a webserver on `:kickstart_port` to wait for a request for the `:kickstart_file`
+  IMPORTANT: Do NOT navigate to the file in your browser or the server will stop and the installer will not be able to find your preseed
+- Wait for ssh login to work with `:ssh_user` and `:ssh_password`
+- `sudo` execute the `:postinstall_files`
+
+
+## Validate the vm
+
+After the OS has been installed you can verify that the machine is configured as intended.
+
+Veewee provides several tests to help you with that. The tests are located under `validation`.
+
+This command executes all tests on the given machine:
+
+    $ veewee vbox validate 'myubuntubox'
+
+This will run some [cucumber test](http://cukes.info/) against the box
+to see if it has the necessary bits and pieces e.g. for vagrant to work.
+
+
+## Export the box for distribution
+
+The following command take care of this:
+
+    $ veewee vbox export 'mybuntubox'
+
+The export format depends on the provider. You can currently choose from these providers:
+
+- `fusion`: exports to an '.ova' file
+- `kvm`: export to a raw '.img' file
+- `vbox`: exports to a '.box' format (e.g. for use in vagrant)
+
+For more details on the providers have a look at [providers.md](providers.md).

data/doc/fusion.md

@@ -0,0 +1,2 @@
+# Coming Soon
+

data/doc/installation.md

@@ -0,0 +1,44 @@
+# Overview
+
+Veewee is a tool to help you building a Virtual Machine from an ISO-file.
+
+
+## Requirements
+
+Please see [requirements.md](requirements.md) for detailed instructions.
+
+
+## Install
+
+These instructions need to be bulked out more, but for now, here is a basic guide to installing Veewee.
+
+The Veewee project is moving quickly and the Rubygem might be outdated. We recommend installing Veewee from source.
+
+__as a gem__
+
+    $ gem install veewee
+
+__from source__
+
+When you cd into the veewee directory, rvm should automatically read the `.rvmrc` file
+and prompt you to verify it - you can do so by pressing `Y`.
+
+This will then create a [gemset](https://rvm.io/gemsets/basics/) for veewee.
+
+    $ git clone https://github.com/jedi4ever/veewee.git
+    $ cd veewee
+    $ gem install bundler
+    $ bundle install
+
+Now start [building baseboxes](running.md) or learn more about [veewee's internals](definition.md)!
+
+### Important Note on testing `kvm` while running from source git repo_
+
+By default the `:kvm` gem group is *disabled* to prevent the installation of `ruby-libvirt` on systems
+that don't need it. This is done by the file `.bundle/config`.
+
+If you do need it, run `bundle install --without restrictions` (restrictions is a dummy name).
+This will change the file `.bundle/config`, which is ignored by Git per default and must not be included in any commits.
+
+As this is a remembered option, you don't have to specify it every time.
+If you want to switch to the default behavior run `bundle install --without kvm` to enable restrictions.

data/doc/kvm.md

@@ -0,0 +1,91 @@
+# KVM Provider
+
+NOTE: Virtualbox doesn't like KVM to be enabled
+
+## Prerequisites
+
+Depending on your operating system you may need to install packages for kvm,
+qemu and libvirt.
+
+If you have problems compiling the libvirt gem, check if you have the 'dev' parts installed too. 
+f.i ``apt-get install libvirt libvirt-dev``
+
+To check if your kernel can run kvm :
+
+    # kvm_ok or kvm-ok command (on Ubuntu at least)
+    kvm_ok
+    # or look for vmx or svm in /proc/cpuinfo
+    egrep '^flags.*(vmx|svm)' /proc/cpuinfo
+
+The kernel modules needed are the following : kvm, kvm_intel or kvm-amd.
+
+### Storage Pool
+
+You need to have at least one storage pool defined in libvirt where your VM
+images will be stored. You can check all available storage pools with
+
+    virsh pool-list
+
+If no storage pool is listed, you can create a new storage pool which saves all
+VM images in the directory /var/lib/libvirt/images with
+
+    mkdir -p /var/lib/libvirt/images
+    cat > /tmp/pool.xml << EOF
+    <pool type="dir">
+      <name>virtimages</name>
+      <target>
+        <path>/var/lib/libvirt/images</path>
+        <format type='qcow2'/>
+      </target>
+    </pool>
+    EOF
+    virsh pool-create /tmp/pool.xml
+
+### Network
+
+You need to have at least one network defined. You can check all available
+networks with
+
+    virsh net-list
+
+If there is no network, consult the documentation of your operating
+system to find out how to creat it. More information can also be found in the
+[libvirt documentation](http://libvirt.org/formatdomain.html#elementsNICS).
+
+If you are using libvirt with a URI different than the default `qemu:///system`,
+you need to create a config file for fog.io. If your libvirt endpoint is
+accessible at `qemu+ssh://cloud@myhost.com/system` you can create the .fog config
+file with
+
+    cat > ~/.fog << EOF
+    :default:
+      :libvirt_uri: qemu+ssh://cloud@myhost.com/system
+    EOF
+
+For more information have a look at the
+[libvirt documentation](http://libvirt.org/drvqemu.html#uris).
+
+## Using VeeWee
+
+You can always get help by using the the built in help with every command.
+e.g. for the build command use
+
+    veewee kvm help build
+
+List available templates
+
+    veewee kvm templates
+
+Use one of the listed templates to define a new box e.g. with
+
+    veewee kvm define 'My Ubuntu 12.10 box' 'ubuntu-12.10-server-amd64'
+
+Build the box using KVM / Quemu (this will take a while)
+
+    veewee kvm build 'My Ubuntu 12.10 box'
+
+You can specify the name of the storage pool and the network to be used when
+building a VM. Use the options`--pool-name` and `--network-name` with the built
+command:
+
+    veewee kvm build 'My Ubuntu 12.10 box' --pool-name virtimages --network-name default

data/doc/providers.md

@@ -0,0 +1,44 @@
+# Providers in Veewee
+
+Initially veewee started as provider for Virtualbox.
+
+From v0.3 VMware Fusion and KVM support are introduced.
+
+
+## [Virtualbox](vbox.md)
+
+To interact with virtualbox, veewee executes shell-commands through the 'VboxManage' command.
+The `virtualbox` gem library proved to be less stable.
+
+To simulate the typing, veewee uses the `VBoxManage` command:
+
+    VBoxManage controlvm 'myubuntu' keyboardputscancode <keycode>
+
+[Scancodes](http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html) are injected directly
+from the keyboard buffer with this command.
+
+And as this buffer is small, we can't type fast(er). This is why you have the delay while veewee types the commands.
+
+Speeding it up, will make the keyboard buffer loose keystrokes.
+
+
+## [VMware Fusion](fusion.md)
+
+To interact with VMware Fusion, we leverage (a currently patched) version of [Fission gem](https://github.com/thbishop/fission).
+
+This takes care of the heavy lifting.
+
+To interact with the screen, veewee enables VNC on the created VMware Fusion machines
+and use the [Ruby-VNC gem](http://code.google.com/p/ruby-vnc/) to send the keystrokes.
+
+Sending keystrokes too fast is a problem as well.
+
+
+## [KVM](kvm.md)
+
+To interact with KVM veewee uses [libvirt support](http://libvirt.org/ruby/) provided through [Fog gem](http://fog.io).
+
+To interact with the screen, veewee enables VNC on the created KVM machines
+and uses the [Ruby-VNC gem](http://code.google.com/p/ruby-vnc/) to send the keystrokes.
+
+Sending keystrokes too fast is a problem as well.

data/doc/requirements.md

@@ -0,0 +1,36 @@
+# Requirements
+
+Veewee is written in Ruby. In order to use it you need Ruby installed and some header files
+in order to compile native extensions that come as dependencies with veewee.
+
+If you already have experiences with Ruby this should be very straightforward.
+
+## Development Libraries
+
+In order to build native rubygems you may need these packages:
+
+    libxslt1-dev
+    libxml2-dev
+    zlib1g-dev
+
+
+## Ruby Environment
+
+First, if you are not using [RVM](https://rvm.io/), it's recommended that you do so
+as veewee will install in it's own [gemset](https://rvm.io/gemsets/basics/) which keeps veewee and it's dependancies
+completely separate from your other Rubygems.
+
+See https://rvm.io/gemsets/basics/ for details if you are new to the concept of 'gemsets'.
+
+TODO ct 2013-02-4 Check if gemset is needed when using bundler
+
+You can install RVM as follows:
+
+    $ bash -s stable < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer)
+    $ source ~/.bash_profile
+
+Now, install Ruby 1.9.2 using RVM:
+
+    $ rvm install 1.9.2
+
+Ok, now that we have RVM installed, you can move on with [installing Veewee](installation.md).

data/doc/running.md

@@ -0,0 +1,67 @@
+# Running veewee commands
+
+The first way to call veewee is through the `veewee` cli command.
+
+Simply type `veewee` to get a list for the basic commands:
+
+    $ veewee
+    Tasks:
+      veewee fusion       # Subcommand for Vmware fusion
+      veewee help [TASK]  # Describe available tasks or one specific task
+      veewee kvm          # Subcommand for kvm
+      veewee vbox         # Subcommand for virtualbox
+      veewee version      # Prints the Veewee version information
+
+Each of these commands provides more details if you execute them.
+
+The following command gives you a list of all available subcommands:
+
+    veewee vbox
+
+Change `vbox` to `fusion` or `kvm` if you want to use a different provider.
+
+
+## Typical Usage
+
+A typical workflow to build a new basebox with veewee would be:
+
+    1. Define a box definition from a template
+    2. Build the box from an ISO file
+    3. Export the box e.g. for distribution
+
+The following commands take care of this:
+
+    $ veewee vbox define 'mybuntubox' 'ubuntu-10.12-amd64'
+    $ veewee vbox build 'mybuntubox'
+    $ veewee vbox export 'mybuntubox'
+
+The export format depends on the provider. You can currently choose from these providers:
+
+- `fusion`: exports to an '.ova' file
+- `kvm`: export to a raw '.img' file
+- `vbox`: exports to a '.box' format (e.g. for use in vagrant)
+
+If you want to tweak things on the box you can login to the box with this command:
+
+    $ veewee vbox ssh 'mybuntubox'
+
+PRO TIP: Be aware that every manual change on the box is considered harmful.
+Have a look at [customize.md](customize.md) to see how you can customize the box in a more 'reproducible' way.
+
+
+## Using veewee as a Vagrant Plugin
+
+You can also use veewee as a [vagrant plugin](http://docs.vagrantup.com/v1/docs/plugins.html).
+
+Veewee introduces the subcommand `basebox` on top of the `vagrant` command:
+
+    $ vagrant basebox
+    Usage: vagrant basebox <command> [<args>]
+
+This allows you to use the 'vagrant' command style, which may feel more natural
+if you are already working with vagrant.
+
+
+### Typical Vagrant Usage
+
+See "[Use it in vagrant](vagrant.md)" for more details.