haskal
/
vagrant
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Some rewording and styling of base box guide

This commit is contained in:
Kieran Pilkington 2010-03-11 23:57:57 +13:00 committed by Mitchell Hashimoto
parent 90d78eb04a
commit 73c734a4b0
1 changed files with 107 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
docs/base_boxes.md
View File

@ -7,16 +7,18 @@ title: Documentation - Base Boxes
<div class="info">
<h3>This topic is for advanced users</h3>
<p>
The following topic is for <em>advanced</em> users. The majority of Vagrant users will
never have to do this. Therefore, only continue if you want to have custom OS or custom
version setups not currently available. This guide also assumes you know how to install
operating systems and are familiar with various UNIX commands you'll need along the way.
The following topic is for <em>advanced</em> users. The majority of Vagrant users
will never have to do this. Therefore, only continue if you want to create a custom
operating system. People wishing to distribute changes to an existing base box should
see the <a href="/docs/getting-started/packaging.html">packaging guide</a>. If you
continue with this guide, you will need a decent knowledge of the command line and
the specific command lines tools available on the system you are installing.
</p>
</div>
A special category known as "base boxes" are the boxes which contain
the bare bones necessary for Vagrant to function. The basic requirements
of the base box are the following:
There are a special category of boxes in Vagrant known as a "base boxes". These boxes
are ones which contain the bare bones necessary for Vagrant to function. The basic
requirements of a base box are as follows:
* VirtualBox Guest Additions for shared folders, port forwarding, etc.
* SSH with basic username/password SSH authentication
@ -24,18 +26,15 @@ of the base box are the following:
* Ruby & RubyGems to install Chef
* Chef for provisioning support
The above are absolutely _required_ by Vagrant to work properly with the
base box. The versions themselves are up to you as long as everything
(Ruby and Chef) works properly together.
The above are absolutely _required_ of a base box in order to work properly with Vagrant.
The versions of those requirements however are up to you, as long as they are working properly.
<div class="info">
<h3>What about security?</h3>
<h3>Isn't a password-less <code>sudo</code> a security risk? What about public/private keys?</h3>
<p>
A common question is "Why the password-less <code>sudo</code>?"
or "What about public/private keys?". Our answer to this is that since Vagrant
targets development environments, security is not a major concern, and we
currently value simplicity over it. In the future we may support keys, password
<code>sudo</code>, etc. but for now this is not possible with Vagrant.
Since Vagrant targets development environments, security is not a major concern, and we
currently value simplicity over it. However, Vagrant is still young, and in the future we may
support keys, password <code>sudo</code>, etc. Right now though, these are not possible.
</p>
</div>
@ -44,45 +43,44 @@ base box. The versions themselves are up to you as long as everything
### Creating and Configuring the Virtual Machine
Base boxes must be created using the [VirtualBox](http://www.virtualbox.org) tool
itself. Since we're working at such a "low level" relative to Vagrant, base boxes
must be created outside of Vagrant. This documentation will not cover the basics
of setting up the virtual machine except for some specific guidelines to follow:
itself. This documentation will not cover the basics of setting up the virtual machine
except for some specific guidelines to follow:
* Make sure you allocate enough **disk space** in a **dynamically resizing drive**.
Typically, we use a 40 GB drive, which is big enough for almost everything.
* Make sure the default memory allocation is _not too high_. Most people don't want
to download a box to find it using 1 GB of RAM. We typically set it at 360 MB to
start, since that is the size of most small slices. The RAM is configurable by the
user at run-time using their Vagrantfile.
* Disable audio, usb, etc. controllers unless they're needed. Most web applications
don't need to play music! Save resources by disabling these features.
user at run-time using their [Vagrantfile](/docs/vagrantfile.html).
* Disable audio, usb, etc. controllers unless they're needed. Most applications
don't need to play music! So save resources by disabling these features.
Now this is **really important**: Make sure the network controller is set to
**NAT**. For port forwarding to work properly, NAT must be used. Bridged
connects are not supported since it requires the machine to specify which
device it is bridged to, which is unknown.
Now go ahead and boot up the Virtual Machine and install the operating system.
Now go ahead and boot up the Virtual Machine, insert the DVD or attach the ISO file
you're installing the operating system from, and follow the install procedure.
<div class="info">
<h3>Size does matter!</h3>
<p>
Having an environment you can send and have others boot up is really neat,
but not very portable if your file is a 5GB download. Even 1GB is pushing
the limits. You should aim for a final Box size of no more than 500mb. In
order to acehive that size, there is a few things you can do.
but not very portable if your file is a 5 GB download. Even 1 GB is pushing
the limits. You should aim for a final Box size of no more than 500 MB. In
order to achieve that size, there is a few things you can do.
</p>
<ul>
<li>Install the operating system without a GUI. That is, when prompted,
deselect the option to install a desktop environment. On a Debian Lenny
install, the final box size difference between an OS with and without a
desktop environment way a whole 1GB. You'll need a good knowledge of
command line commands if you go this route.</li>
install, the final size difference between an OS with and without a
desktop environment was a whole 1 GB.</li>
<li>Clear the system cache before you export at the end. You don't need tmp
files, or cache system packages. In the case of Debian or Ubuntu based OSs,
you can clean the cache with `apt-get clean`.</li>
files, or cached system packages. In the case of Debian or Ubuntu based
operating systems, you can clean the cache with `apt-get clean`.</li>
<li>Where possible, avoid installing all the documentation. When installing
RubyGems for example, append `--no-rdoc --no-ri` to the install command.</li>
RubyGems for example, append `--no-rdoc --no-ri` to the install commands.</li>
</ul>
</div>
@ -101,18 +99,26 @@ Now go ahead and boot up the Virtual Machine and install the operating system.
<li>Main account login: vagrant</li>
<li>Main account password: vagrant</li>
</ul>
<p>
Also keep in mind that, in order to simplify configurations, Vagrant make
assumptions about the main account login/password. It will assume the text
'vagrant' for both values. If any of these are changed, you will need to
remember to specify them in the Vagrantfile using the appropriate configuration
methods before packaging the box.
</p>
</div>
### Setup Permissions
Once the VM is created, boot it up. Then lets start by making sure the user has proper
permissions. Specifically the main user should have **password-less `sudo` privileges**.
We do this by running `su` and entering the root password you entered during the
installation of the operating system. Once logged in, run `visudo` and and set the admin
group to use no password.
Once the Virtual Machine is created, boot it up if it isn't already. Then lets
start by making sure the default account has proper permissions. Specifically,
the main user should have **password-less `sudo` privileges**. We do this by
running `su` and entering the root password you entered during the installation
of the operating system. Once logged in, run `visudo` and set the admin group
to use no password.
**Note:** Some bare bones systems will not include `sudo` by default. If `visudo` is not an
available command, install the `sudo` package for your operating system.
**Note:** Some bare bones systems will not include `sudo` by default. If `visudo`
is not an available command, install the `sudo` package for your operating system.
The line you should add in the `visudo` configuration to do that looks like this:
@ -120,11 +126,10 @@ The line you should add in the `visudo` configuration to do that looks like this
%admin ALL=NOPASSWD: ALL
{% endhighlight %}
If you unfamiliar with vi, the editor `visudo` uses, press 'i' to start input, ESC to stop
input, CTRL+X to quit, type 'Y' to save, then hit Enter/Return. Once that is setup, you
may need to make the 'admin' group, and you then need to assign the main user to that group
(on Debian and Ubuntu systems, this is done with groupadd and usermod. Consult the documentation
for the commands your operating system uses).
Once that is setup, you may need to make the 'admin' group, and you then need to
assign the main user to that group (on Debian and Ubuntu systems, this is done with
the groupadd and usermod utilities. Consult the documentation for the commands your
operating system uses).
Then restart sudo using `/etc/init.d/sudo restart` (command may defer on operating systems).
Finally, verify that sudo works without a password, but running `exit` out of the root
@ -132,10 +137,10 @@ account, then `sudo which sudo`. You should get output similar to `/usr/bin/sudo
### Install VirtualBox Guest Additions
Now we have the permissions, lets get the operating system running a bit smoother.
There are various guides across the internet explaining how to set up the Virtualbox Guest
Additions, but for most unix-based systems, the following will work just fine.
Now we have the permissions, lets gets shared folders and port forwarding working so we
can harness the full power Vagrant has to offer. There are various guides across the
internet explaining how to set up the Virtualbox Guest Additions, but for most unix-based
systems, the following will work just fine.
First, build the necessary packages. You may have to look these up for your system,
but they should be fairly similar. On Ubuntu and Debian based systems they are as follows:
@ -146,7 +151,7 @@ $ sudo apt-get install linux-headers-$(uname -r) build-essential
Next, make sure to insert the guest additions image by using the GUI and clicking
on "Devices" followed by "Install Guest Additions.". Then run the following to
mount the cdrom:
mount the CD Rom:
{% highlight bash %}
$ sudo mount /media/cdrom
@ -159,42 +164,48 @@ it is the following:
sudo sh /cdrom/VBoxLinuxAdditions-x86.run
{% endhighlight %}
The install will probably warn you about not installing OpenGL or Window System Drivers,
but this is okay.
If you didn't install a Desktop environment when you installed the operating system,
as recommended to reduce size, the install of the VirtualBox additions should warn
you about the lack of OpenGL or Window System Drivers, but you can safely ignore this.
### Boot and Setup Basic Software
We need to setup the software Vagrant relies on. The _required_ software is listed below:
* **Ruby** - Use the dev package so mkmf is present for Chef
* **RubyGems** - For Chef
* **Chef** - For provisioning support.
* **Ruby** - Use the dev package so mkmf is present for Chef to compile
* **RubyGems** - To install the Chef gem
* **Chef** gem - For provisioning support (gem install chef)
* **SSH**
These are typically straightforward to install the details won't be gone into here. If
promoted, make sure that the SSH uses **basic username/password authentication** and
write down the username/password.
These are typically straightforward to install using the operating systems default package
management tools, so the details won't be gone into here. If promoted, make sure that the
SSH package is set to use **basic username/password authentication** and write down the
username/password for later.
### Copy the MAC Address
Nearly done. When the OS installs, it typically sets up the basic network devices (eth0 and so on)
automatically. This includes setting the MAC address of these devices. Since configuring
these network devices is often very OS-specific, instead of Vagrant dynamically setting
this at runtime, it forces VirtualBox to use a specific MAC address. This requires
little work on your end. Simply run `sudo ifconfig` or the equivalent and copy the
MAC address down somewhere on your host machine. A screenshot of this is shown
below:
When the operating system was installed, it typically sets up the basic network devices
(eth0 and so on) automatically. This includes setting the MAC address of these devices.
Since configuring these network devices is often very OS-specific, instead of Vagrant
dynamically setting this at runtime, it forces VirtualBox to use a specific MAC address.
This requires little work on your end, but only needs to be done once per base box.
Simply run `sudo ifconfig` or the equivalent and copy the MAC address down somewhere on
your host machine. A screenshot of this is shown below:
![Copying MAC Address](/images/base_box_mac.jpg)
Now go ahead and shutdown the virtual machine before continuing.
This MAC Address will be used soon. Go ahead and shutdown the virtual machine before continuing.
### Export the Virtual Machine
Next, export the virtual machine with "File" then "Export Appliance." Export it to
any folder, but make sure the filename is set to `box.ovf`, which is the Vagrant default.
You may actually name this ovf file anything you wish, but naming it the default
has no consequence and will make your life easier.
You may actually name this ovf file anything you wish, but naming it the default has
no consequence and will make your life easier.
The export process can take several minutes. While that is running, you can progress
onto the next step.
### Setup the Vagrantfile
@ -227,10 +238,20 @@ end
### Package and Distribute
With that done, the final step is to package the contents into a "box" file
and distribute it. The format of "box" files is nothing special: they're
simply tar files. The biggest thing is to make sure that all the files in the
archive are top-level, meaning that the files aren't in a subdirectory.
Now that you have the exported virtual machine and the necessary Vagrantfile,
the final step is to package the contents into a "box" file and distribute it.
The format of "box" files is nothing special: they're simply tar files. The
biggest thing is to make sure that all the files in the archive are top-level,
meaning that the files aren't in a subdirectory.
<div class="info">
<h3>Hold on, why not .gz, .bz2, or .7z ?!</h3>
<p>
Simple. When you export the virtual machine from VirtualBox, it is
already compressed. Adding additional compression is slower and yields
no smaller box size than just using tar.
</p>
</div>
The following shows how to build the tar archive properly:
@ -241,14 +262,19 @@ box.mf box.ovf drive.vmdk Vagrantfile
$ tar -cvf package.box ./*
{% endhighlight %}
The result is `package.box` which can be distributed and installed by
Vagrant user. Don't forget to test it yourself!
As with the export, this can take several minutes. The result is a file called
`package.box` which can be distributed and installed by Vagrant users.
<div class="info">
<h3>Hold on, why not .gz, .bz2, or .7z ?!</h3>
<p>
Simple. When you export the virtual machine from VirtualBox, it is
already compressed. Adding additional compression is slower and yields
no smaller box size than just using tar.
</p>
</div>
It would be a good idea to try and add this box to your own Vagrant installation,
setup a test environment, and try ssh in.
{% highlight bash %}
$ cd export_directory
$ vagrant box add my_box package.box
$ mkdir test_environment
$ cd test_environment
$ vagrant init
# open up Vagrantfile and set config.vm.box to 'my_box'
$ vagrant up
$ vagrant ssh
{% endhighlight %}