Permalink
Browse files

Split instructions for vagrant into sub-files

Update the instructions for creating a new Veewee definition.

Uses Ubuntu 12.10.
  • Loading branch information...
1 parent cb77302 commit 20219322b531940b82b3a60b594d0d540b71e7e6 Christian Trabold committed Feb 3, 2013
Showing with 183 additions and 85 deletions.
  1. +26 −0 doc/contribute.md
  2. +49 −0 doc/customize.md
  3. +108 −85 doc/vagrant.md
View
@@ -0,0 +1,26 @@
+# Contribute or Improving a Veewee Template
+
+## How to add a new OS/installation (needs some love)
+
+I suggest the easiest way is to get an account on github and fork of the veewee repository
+
+ $ git clone https://github.com/*your account*/veewee.git
+ $ cd veewee
+ $ gem install bundler
+ $ bundle install
+
+If you don't use rvm, be sure to execute vagrant through bundle exec
+
+ $ alias veewee="bundle exec veewee"
+
+Start of an existing one
+
+ $ veewee vbox define 'mynewos' 'ubuntu...'
+
+- Do changes in the currentdir/definitions/mynewos
+- When it builds ok, move the definition/mynewos to a sensible directory under templates
+- commit the changes (git commit -a)
+- push the changes to github (git push)
+- go to the github gui and issue a pull request for it
+
+## If you have a setup working, share your 'definition' with me. That would be fun!
View
@@ -0,0 +1,49 @@
+# Customize Veewee Definitions
+
+## definition.rb
+
+The core definition of a box. All crucial properties are defined here.
+
+The `boot_cmd_sequence` is probably the most interesting because it allows you to override the initial commands
+(like keyboard layout) that are fired up in the first boot sequence.
+
+All other settings are used internally by veewee, the virtualization tool or simply for choosing the right ISO:
+
+ Veewee::Definition.declare( {
+ :cpu_count => '1',
+ :memory_size=> '256',
+ :disk_size => '10140',
+ :disk_format => 'VDI',
+ :disk_variant => 'Standard',
+ :os_type_id => 'Ubuntu',
+ :iso_file => "ubuntu-12.10-server-i386.iso",
+ :iso_src => "http://releases.ubuntu.com/precise/ubuntu-12.10-server-i386.iso",
+ :iso_md5 => "3daaa312833a7da1e85e2a02787e4b66",
+ :iso_download_timeout => "1000",
+ :boot_wait => "10",
+ :boot_cmd_sequence => [
+ '<Esc><Esc><Enter>',
+ '/install/vmlinuz noapic preseed/url=http://%IP%:%PORT%/preseed.cfg ',
+ 'debian-installer=en_US auto locale=en_US kbd-chooser/method=us ',
+ 'hostname=%NAME% ',
+ 'fb=false debconf/frontend=noninteractive ',
+ 'console-setup/ask_detect=false console-setup/modelcode=pc105 console-setup/layoutcode=us ',
+ 'initrd=/install/initrd.gz -- <Enter>'
+ ],
+ :kickstart_port => "7122",
+ :kickstart_timeout => "10000",
+ :kickstart_file => "preseed.cfg",
+ :ssh_login_timeout => "10000",
+ :ssh_user => "vagrant",
+ :ssh_password => "vagrant",
+ :ssh_key => "",
+ :ssh_host_port => "2222", :ssh_guest_port => "22",
+ :sudo_cmd => "echo '%p'|sudo -S sh '%f'",
+ :shutdown_cmd => "shutdown -H",
+ :postinstall_files => [ "postinstall.sh"],
+ :postinstall_timeout => "10000"
+ })
+
+IMPORTANT: If you need to change values in the templates, be sure to run `veewee vbox undefine` to remove the old definition and then `veewee vbox define` again to copy the updated template files into the definition.
+
+PRO Tipp: If you change template settings please let us know why. We are very interested in improving the templates.
View
@@ -1,119 +1,142 @@
-## Define a new box
-Let's define a Ubuntu 10.10 server i386 basebox called myunbuntubox
-this is essentially making a copy based on the templates provided above.
-
- $ veewee vbox define 'myubuntubox' 'ubuntu-10.10-server-i386'
- The basebox 'myubuntubox' has been successfully created from the template ''ubuntu-10.10-server-i386'
- You can now edit the definition files stored in definitions/myubuntubox
- or build the box with:
+# Define a new box
+
+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`. Here you find all the templates you can use.
+
+The folder name has a schema to help you choosing the right template:
+
+ ubuntu-12.10-server-i386[-netboot]
+ ^ ----- install flavor (optional)
+ ^ ----- architecture
+ ^ ----- version
+ ^ ----- OS name
+
+
+## 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'
--> This copies over the templates/ubuntu-10.10-server-i386 to definition/myubuntubox
+Verify that all files are in place:
$ ls definitions/myubuntubox
- definition.rb postinstall.sh postinstall2.sh preseed.cfg
-
-## Optionally modify the definition.rb , postinstall.sh or preseed.cfg
-
- Veewee::Definition.declare( {
- :cpu_count => '1', :memory_size=> '256',
- :disk_size => '10140', :disk_format => 'VDI', :disk_variant => 'Standard',
- :os_type_id => 'Ubuntu',
- :iso_file => "ubuntu-10.10-server-i386.iso",
- :iso_src => "http://releases.ubuntu.com/maverick/ubuntu-10.10-server-i386.iso",
- :iso_md5 => "ce1cee108de737d7492e37069eed538e",
- :iso_download_timeout => "1000",
- :boot_wait => "10",
- :boot_cmd_sequence => [
- '<Esc><Esc><Enter>',
- '/install/vmlinuz noapic preseed/url=http://%IP%:%PORT%/preseed.cfg ',
- 'debian-installer=en_US auto locale=en_US kbd-chooser/method=us ',
- 'hostname=%NAME% ',
- 'fb=false debconf/frontend=noninteractive ',
- 'console-setup/ask_detect=false console-setup/modelcode=pc105 console-setup/layoutcode=us ',
- 'initrd=/install/initrd.gz -- <Enter>'
- ],
- :kickstart_port => "7122", :kickstart_timeout => "10000",:kickstart_file => "preseed.cfg",
- :ssh_login_timeout => "10000",:ssh_user => "vagrant", :ssh_password => "vagrant",:ssh_key => "",
- :ssh_host_port => "2222", :ssh_guest_port => "22",
- :sudo_cmd => "echo '%p'|sudo -S sh '%f'",
- :shutdown_cmd => "shutdown -H",
- :postinstall_files => [ "postinstall.sh"],:postinstall_timeout => "10000"
- }
- )
-
-If you need to change values in the templates, be sure to run the rake undefine, the rake define again to copy the changes across.
-
-## Getting the cdrom file in place
-Put your isofile inside the 'currentdir'/iso directory or if you don't run
+ definition.rb postinstall.sh preseed.cfg
- $ veewee vbox build 'myubuntubox'
+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 the template.
+
+A definition usually consists of these files:
+
+ definition.rb - Core definition of a box like CPU, RAM and the commands for the initial boot sequence
+ postinstall.sh - Steps that run 'after' installing the OS
+ preseed.cfg - Default options for the installer. See https://help.ubuntu.com/12.04/installation-guide/i386/preseed-using.html
+
+Newer definitions contain of even more files to get a finer separation of concerns for the installation.
+
+TODO ct 2013-02-3 Add link to details
+
+
+## Getting the CD-ROM file in place
+
+The CD-ROM file (.iso) file is needed to start the installation process.
+
+Depending on your internet connection fetching a ISO file can take several minutes.
+
+If you already have an .iso file for the desired distribution you can put the isofile inside the `./iso` directory.
+
+Create this directory if it does not exist. Otherwise Veewee will ask you to download the ISO file fro the web.
-- the build assumes your iso files are in 'currentdir'/iso
-- if it can not find it will suggest to download the iso for you
-- use '--force' to overwrite an existing install
## Build the new box:
+In order to build the box execute this command:
+
$ veewee vbox build 'myubuntubox'
-- This 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 (don't 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 , :ssh_password
-- Sudo execute the :postinstall_files
+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
-## 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 against the box to see if it has the necessary bits and pieces for vagrant to work
+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 vm to a .box file
+In order to use the box in Vagrant we need to export the VM as a [Basebox](http://vagrantup.com/v1/docs/base_boxes.html):
+
$ vagrant basebox export 'myubuntubox'
-this is actually calling - vagrant package --base 'myubuntubox' --output 'boxes/myubuntubox.box'
+This is actually calling `vagrant package --base 'myubuntubox' --output 'boxes/myubuntubox.box'`.
-this will result in a myubuntubox.box
+The machine gets shut down, exported and will be packed in a `myubuntubox.box` file inside the current directory.
-## Add the box as one of your boxes
-To import it into vagrant type:
- $ vagrant box add 'myubuntubox' 'myubuntubox.box'
+## Add the new box as one of your Vagrant boxes
-## Use it in vagrant
+These steps are specific to vagrant. To import it into Vagrant's box repository simply type:
-To use it:
-
- $ vagrant init 'myubuntubox'
- $ vagrant up
- $ vagrant ssh
+ $ vagrant box add 'myubuntubox' 'myubuntubox.box'
-## How to add a new OS/installation (needs some love)
+The parameter 'myubuntubox' sets the name of the box that is used by Vagrant to reference the box e.g. in the `Vagrantfile`.
-I suggest the easiest way is to get an account on github and fork of the veewee repository
+See http://docs.vagrantup.com/v1/docs/boxes.html for more details.
- $ git clone https://github.com/*your account*/veewee.git
- $ cd veewee
- $ gem install bundler
- $ bundle install
-If you don't use rvm, be sure to execute vagrant through bundle exec
+## Use it in vagrant
- $ alias veewee="bundle exec veewee"
+To use your newly generated box in a fresh project execute these commands:
-Start of an existing one
+ $ vagrant init 'myubuntubox'
- $ veewee vbox define 'mynewos' 'ubuntu...'
+If you already have a project running with Vagrant, open the `Vagrantfile` and change the value of `config.vm.box`
+to the new boxname:
-- Do changes in the currentdir/definitions/mynewos
-- When it builds ok, move the definition/mynewos to a sensible directory under templates
-- commit the changes (git commit -a)
-- push the changes to github (git push)
-- go to the github gui and issue a pull request for it
+ Vagrant::Config.run do |config|
+ config.vm.box = "myubuntubox"
-## If you have a setup working, share your 'definition' with me. That would be fun!
+Now start the new environment with `vagrant up` and log in with `vagrant ssh` to enjoy the joys of your new environment.

0 comments on commit 2021932

Please sign in to comment.