Permalink
Browse files

Optimize content structure / remove duplicates

  • Loading branch information...
1 parent 8ab83e0 commit 91653300c84734d5d3e41b0a55052d479cf0939d Christian Trabold committed Feb 5, 2013
Showing with 205 additions and 188 deletions.
  1. +94 −0 doc/customize.md
  2. +103 −81 doc/definition.md
  3. +0 −10 doc/running.md
  4. +8 −97 doc/vagrant.md
View
@@ -1,5 +1,51 @@
# Customize Veewee Definitions
+Definitions are stored under a directory 'definitions' relative to the current directory.
+
+ .
+ ├── definitions
+ │   └── myubuntubox
+ │   ├── <preseed.cfg, kickstart.cfg, ...>
+ │   ├── base.sh
+ │   ├── cleanup.sh
+ │   ├── chef.sh
+ │   ├── puppet.sh
+ │   ├── ruby.sh
+ │   ├── virtualbox.sh
+ │   └── ....sh
+ └── README.md
+
+The file `definition.rb` contains all the parameters to define the machine to be build (see below):
+
+ - memorysize
+ - number of cpus
+ - user account and password
+ - sudo command
+ - shutdown command
+ - URL and checksum to download the ISO
+
+When a new machine boots, it will typically fetch its initial configuration file over http from a _kickstart_ file
+defined in `kickstart_file`. These files are usually named `preseed.cfg` or `ks.cfg`.
+
+You can define multiple files by providing an array of filenames:
+
+ :postinstall_files => [ "postinstall.sh", "postinstall_2.sh" ],
+
+Once the initial installation is done, veewee will execute each `.sh` file on the machine.
+
+INFO: The main reason for splitting up the `postinstall.sh` we used to have, is to make the steps more reusable
+for different virtualization systems. For example there is no need to install the Virtualbox Guest Additions
+on kvm or VMware Fusion.
+
+
+### Using ERB in files
+
+Add `.erb` to your files in a definition and they will get rendered.
+
+This is useful for generating kickstart, post-install at runtime.
+
+Thanks @mconigilaro for the contribution!
+
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
@@ -56,3 +102,51 @@ All other settings are used internally by veewee, the virtualization tool or sim
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 Tip: If you change template settings please let us know why. We are very interested in improving the templates.
+
+
+## Provider `vm_options`
+
+Each provider _can_ take options that are specific to them; more details will
+be available in each provider documentation but let's have a quick overview:
+
+ Veewee::Definition.declare({
+ :cpu_count => '1',
+ :memory_size => '256',
+ :disk_size => '10140',
+ :disk_format => 'VDI',
+ :disk_variant => 'Standard',
+ # […]
+ :postinstall_files => [ "postinstall.sh" ],
+ :postinstall_timeout => "10000",
+ :kvm => {
+ :vm_options => [
+ 'network_type' => 'bridge',
+ 'network_bridge_name' => 'brlxc0'
+ ]
+ },
+ :virtualbox => {
+ :vm_options => [
+ 'pae' => 'on',
+ 'ioapic' => 'one'
+ ]
+ }
+ })
+
+This box will have `pae` and `ioapic` enabled on Virtualbox, and will use
+the `brlxc0` bridge on with kvm (on libvirt).
+
+
+## Changes between v0.2 -> v0.3
+
+1. The `Veewee::Session.declare` is now _deprecated_ and you should use `Veewee::Definition.declare`.
+ 'Postinstall_files' prefixed with an _underscore_ are not executed by default:
+ .
+ ├── definitions
+ │   └── myubuntubox
+ │   ├── _postinstall.sh # NOT executed
+ │   ├── postinstall_2.sh # GETS executed
+ You can enforce including or excluding files with the `--include` and `--exclude` flag when using the `<build>` command.
+ This allows you to use different scripts for installing ruby or to disable the installation of puppet or chef.
+2. The default user of definitions is now 'veewee' and not 'vagrant'.
+ This is because on other virtualizations like fusion and `kvm`, there is not relationship with the 'vagrant'.
+ The User 'vagrant' is created by the `vagrant.sh` script and not by the preseed or kickstart file.
View
@@ -10,10 +10,25 @@ 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
+
## Creating a definition
-A definition is created by 'cloning' a *template*.
+A definition is created by 'cloning' a *template* into the `definitions` folder.
To create a definition you use the `define` subcommand:
@@ -23,106 +38,113 @@ 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'
-## Modifying a definition
-Definitions are stored under a directory 'definitions' relative to the current directory.
+## Remove a definition
+
+If you change your mind and want to get rid of a definition simply call this command:
+
+ veewee vbox undefine 'myubuntubox'
- .
- ├── definitions
- │   └── myubuntubox
- │   ├── <preseed.cfg, kickstart.cfg, ...>
- │   ├── base.sh
- │   ├── cleanup.sh
- │   ├── chef.sh
- │   ├── puppet.sh
- │   ├── ruby.sh
- │   ├── virtualbox.sh
- │   └── ....sh
- └── README.md
+Or you can remove the folder under `definitions`:
-The file `definition.rb` contains all the parameters to define the machine to be build:
+ rm -r ./definitions/myubuntubox
- - memorysize
- - number of cpus
- - user account and password
- - sudo command
- - shutdown command
- - URL and checksum to download the ISO
-When a new machine boots, it will typically fetch its initial configuration file over http from a _kickstart_ file
-defined in `kickstart_file`. These files are usually named `preseed.cfg` or `ks.cfg`.
+## Example
-You can define multiple files by providing an array of filenames:
+Let's say you'd like to have a *Ubuntu 12.10 server (i386)* basebox.
- :postinstall_files => [ "postinstall.sh", "postinstall_2.sh" ],
+Go and find the template `ubuntu-12.10-server-i386` within `templates` to verify you can create a definition.
-Once the initial installation is done, veewee will execute each `.sh` file on the machine.
+Use the `veewee vbox define` command to create your definition with a custom name.
-INFO: The main reason for splitting up the `postinstall.sh` we used to have, is to make the steps more reusable
-for different virtualization systems. For example there is no need to install the Virtualbox Guest Additions
-on kvm or VMware Fusion.
+ 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`:
-### Changes between v0.2 -> v0.3
+ $ 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'
-1. The `Veewee::Session.declare` is now _deprecated_ and you should use `Veewee::Definition.declare`.
- 'Postinstall_files' prefixed with an _underscore_ are not executed by default:
- .
- ├── definitions
- │   └── myubuntubox
- │   ├── _postinstall.sh # NOT executed
- │   ├── postinstall_2.sh # GETS executed
- You can enforce including or excluding files with the `--include` and `--exclude` flag when using the `<build>` command.
- This allows you to use different scripts for installing ruby or to disable the installation of puppet or chef.
-2. The default user of definitions is now 'veewee' and not 'vagrant'.
- This is because on other virtualizations like fusion and `kvm`, there is not relationship with the 'vagrant'.
- The User 'vagrant' is created by the `vagrant.sh` script and not by the preseed or kickstart file.
+Verify that all files are in place:
+ $ ls definitions/myubuntubox
+ definition.rb postinstall.sh preseed.cfg
-### Using ERB in files
+You now can inspect and modify the defaults to your needs (see below) or start building the box with this command:
-Add `.erb` to your files in a definition and they will get rendered.
+ veewee vbox build 'myubuntubox'
-This is useful for generating kickstart, post-install at runtime.
+Veewee now asks for downloading the ISO and will start his magic.
-Thanks @mconigilaro for the contribution!
+## Modify the definition (optional)
-## List existing definitions
+You can tweak and customize every detail of the box by modifying and extending the (sane) default settings
+that come with a template.
- veewee vbox list
+If you want to modify these settings take a look at [customization instructions](customize.md).
-## Remove a definition
- veewee vbox undefine 'myubuntubox'
+## 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:
-## Provider `vm_options`
-
-Each provider _can_ take options that are specific to them; more details will
-be available in each provider documentation but let's have a quick overview:
-
- Veewee::Definition.declare({
- :cpu_count => '1',
- :memory_size => '256',
- :disk_size => '10140',
- :disk_format => 'VDI',
- :disk_variant => 'Standard',
- # […]
- :postinstall_files => [ "postinstall.sh" ],
- :postinstall_timeout => "10000",
- :kvm => {
- :vm_options => [
- 'network_type' => 'bridge',
- 'network_bridge_name' => 'brlxc0'
- ]
- },
- :virtualbox => {
- :vm_options => [
- 'pae' => 'on',
- 'ioapic' => 'one'
- ]
- }
- })
-
-This box will have `pae` and `ioapic` enabled on Virtualbox, and will use
-the `brlxc0` bridge on with kvm (on libvirt).
+- `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)
View
@@ -64,14 +64,4 @@ if you are already working with vagrant.
### Typical Vagrant Usage
-A typical workflow would be:
-
- $ vagrant basebox define 'mybuntubox' 'ubuntu-10.12-amd64'
- $ vagrant basebox build 'mybuntubox'
- $ vagrant basebox export 'mybuntubox'
-
-Now you can import the generated '.box' file to the vagrant box repository:
-
- $ vagrant basebox add 'mybuntubox' 'mybuntubox.box'
-
See "[Use it in vagrant](vagrant.md)" for more details.
Oops, something went wrong.

0 comments on commit 9165330

Please sign in to comment.