Skip to content

Commit

Permalink
Split instructions for vagrant into sub-files
Browse files Browse the repository at this point in the history 
Update the instructions for creating a new Veewee definition.

Uses Ubuntu 12.10.
  • Loading branch information
@ctrabold
ctrabold committed Feb 3, 2013
1 parent cb77302 commit 2021932
Show file tree
Hide file tree
Showing 3 changed files with 183 additions and 85 deletions.
26 changes: 26 additions & 0 deletions doc/contribute.md
View file
@@ -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!
49 changes: 49 additions & 0 deletions doc/customize.md
View file
@@ -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.
193 changes: 108 additions & 85 deletions doc/vagrant.md
View file
@@ -1,119 +1,142 @@
## Define a new box # 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 uses `definitions` to create new boxes. Every definition is based on a `template`.


$ veewee vbox define 'myubuntubox' 'ubuntu-10.10-server-i386' A `template is represented by a sub-directory in the folder `templates`. Here you find all the templates you can use.
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 The folder name has a schema to help you choosing the right template:
or build the box with:
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' 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 $ ls definitions/myubuntubox
definition.rb postinstall.sh postinstall2.sh preseed.cfg definition.rb postinstall.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


$ 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: ## Build the new box:


In order to build the box execute this command:

$ veewee vbox build 'myubuntubox' $ veewee vbox build 'myubuntubox'


- This will create a machine + disk according to the definition.rb TIPP: If you already built a box with that name you can use `--force` to overwrite an existing installation.
- Note: :os_type_id = The internal Name Virtualbox uses for that Distribution
- Mount the ISO File :iso_file The command will run the following routines behind the scenes:
- Boot up the machine and wait for :boot_time
- Send the keystrokes in :boot_cmd_sequence - It will create a machine + disk according to the `definition.rb`
- 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) - Note: `:os_type_id` = The internal Name Virtualbox uses for that Distribution
- Wait for ssh login to work with :ssh_user , :ssh_password - Mount the ISO File `:iso_file`
- Sudo execute the :postinstall_files - 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' $ 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 ## 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' $ 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 box add 'myubuntubox' 'myubuntubox.box'

$ vagrant init 'myubuntubox'
$ vagrant up
$ vagrant ssh


## 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 Vagrant::Config.run do |config|
- When it builds ok, move the definition/mynewos to a sensible directory under templates config.vm.box = "myubuntubox"
- 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! 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.