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

Updating base box creation guide 

* Adding helpful info bubbles, questions/answers, and tips
* Correcting/adding various bits to make the process smoother
This commit is contained in:
Kieran Pilkington 2010-03-10 09:49:19 +13:00 committed by Mitchell Hashimoto
parent 6eedab2d74
commit 6dddd2dc1c
3 changed files with 116 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
css/screen.css
View File

@ -154,6 +154,24 @@ blockquote {
font-style: normal;
}
/* ----- info boxes ----- */
.info {
padding-left: 52px;
margin-top: 0px;
margin-bottom: 10px;
border: 1px dotted #DDD;
background-image: url(/images/icons/error.png);
background-position: 10px 10px;
background-color: #EEEEEE;
background-repeat: no-repeat;
color: #000;
font-size: 0.8em;
}
.info h3 {
font-size: 1.3em;
}
/* -------------------------------
HEADER

137
docs/base_boxes.md
View File

@ -4,30 +4,40 @@ title: Documentation - Base Boxes
---
# 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.
</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:
* SSH with basic username/password SSH authentication
* Password-less `sudo`
* Ruby
* RubyGems
* Chef
* VirtualBox Guest Additions for shared folders, port forwarding, etc.
* SSH with basic username/password SSH authentication
* Password-less `sudo` for the main account
* 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) work properly together.
(Ruby and Chef) works properly together.
**What about security?** A common question is "Why the password-less `sudo`?"
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
`sudo`, etc. but for now this is not possible with Vagrant.
**Note:** This topic is _advanced_ and in general most users of Vagrant will
never have to do this. This is only useful for those wishing to have custom
OS or custom version setups.
<div class="info">
<h3>What about security?</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.
</p>
</div>
## Creating Base Boxes
@ -52,14 +62,46 @@ Now this is **really important**: Make sure the network controller is set to
connects are not supported since it requires the machine to specify which
device it is bridged to, which is unknown.
For consistency across various Vagrant boxes, if you plan to distribute the box,
please follow these conventions where possible:
Now go ahead and boot up the Virtual Machine and install the operating system.
* Hostname: vagrant-[os-name], e.g. vagrant-debian-lenny
* Domain: vagrantup.com
* Root Password: vagrant
* Main user username: vagrant
* Main user password: vagrant
<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.
</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>
<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>
<li>Where possible, avoid installing all the documentation. When installing
RubyGems for example, append `--no-rdoc --no-ri` to the install command.</li>
</ul>
</div>
<div class="info">
<h3>Convention over Configuration</h3>
<p>
Choice is a good thing, so just about everything in Vagrant can be changed.
However, it's easier for others to use Vagrant when you follow a set of
conventions. Now, while these aren't enforced conventions, if you plan to
distribute the box, it is recommended you follow the following where possible:
</p>
<ul>
<li>Hostname: vagrant-[os-name], e.g. vagrant-debian-lenny</li>
<li>Domain: vagrantup.com</li>
<li>Root Password: vagrant</li>
<li>Main account login: vagrant</li>
<li>Main account password: vagrant</li>
</ul>
</div>
### Setup Permissions
@ -67,18 +109,26 @@ Once the VM is created, boot it up. Then lets start by making sure the user has
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. The line in the `visudo` configuration to do that looks like this:
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.
The line you should add in the `visudo` configuration to do that looks like this:
{% highlight bash %}
%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, and type 'Y' to save. Once that is setup, you may need to make the
'admin' group, and you then need to assign the main user to that group.
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).
Finally, verify that sudo works without a password, but running 'exit' out of the root
account, then `sudo su sudo`. You should get output similar to '/usr/bin/sudo'.
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
account, then `sudo which sudo`. You should get output similar to `/usr/bin/sudo`.
### Install VirtualBox Guest Additions
@ -95,9 +145,8 @@ $ sudo apt-get install linux-headers-$(uname -r) build-essential
{% endhighlight %}
Next, make sure to insert the guest additions image by using the GUI and clicking
on "Devices" followed by "Install Guest Additions.". Now, depending on your operating
system, the guest additions may or may not be mounted. If /cdrom doesn't exist, then
run the following to mount the cdrom:
on "Devices" followed by "Install Guest Additions.". Then run the following to
mount the cdrom:
{% highlight bash %}
$ sudo mount /media/cdrom
@ -111,25 +160,24 @@ 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. Once setup, shut down the VM.
but this is okay.
### Boot and Setup Basic Software
Nearly done. We need to setup the software Vagrant relies on. The
_required_ software is listed below:
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.
* **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 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.
### Copy the MAC Address
When the OS installs, it typically sets up the basic network devices (eth0 and so on)
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
@ -139,6 +187,8 @@ below:
![Copying MAC Address](/images/base_box_mac.jpg)
Now 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
@ -192,4 +242,13 @@ $ 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!
Vagrant user. Don't forget to test it yourself!
<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>

BIN
images/icons/error.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.2 KiB