diff --git a/_layouts/getting_started.html b/_layouts/getting_started.html index e641dceaf..0a6e6eb7a 100644 --- a/_layouts/getting_started.html +++ b/_layouts/getting_started.html @@ -13,7 +13,6 @@
  • Packaging
  • Teardown
  • Rebuild Instantly
    • -
  • Windows
    • diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index cebaa156d..ad793dfc5 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -31,6 +31,21 @@ Here is a link directly to the [download page](http://www.virtualbox.org/wiki/Do

    +## Setting up Ruby and RubyGems + +Although Vagrant is written in Ruby, web developers from many different languages +come to use it (Python, Java, Clojure, etc.). Therefore, if you've never setup Ruby +or RubyGems before, please check out our basic guides, written for different +popular operating systems listed below: + +* [Windows](/docs/getting-started/setup/windows.html) +* [Mac OS X](/docs/getting-started/setup/mac.html) +* [Ubuntu](/docs/getting-started/setup/ubuntu.html) + +Is your OS not listed above? Feel free ask for help via our [support channels](/support.html). +Or if you figure it out on your own, let us know how and we'll gladly update the +website. + ## Install Vagrant Vagrant is packaged as a [RubyGem](http://rubygems.org/). Since Vagrant is written diff --git a/docs/getting-started/setup/windows.md b/docs/getting-started/setup/windows.md new file mode 100644 index 000000000..0181cc560 --- /dev/null +++ b/docs/getting-started/setup/windows.md @@ -0,0 +1,82 @@ +--- +layout: getting_started +title: Windows +--- +# Windows + +
    +

    Windows Support

    +

    + Windows support is a recent addition to vagrant so if you do experience trouble + or find this section hard to follow, please see the support page + and let us know so we can help you. Our goal is to make Vagrant the best tool + for the job on as many platforms as possible. +

    +

    + All Windows testing has been performed from the vanilla Windows XP command prompt. Cygwin support + is planned but Vista and Windows 7 testing will have to be a community effort. If you are interested + in testing the latest updates please checkout the github page. +

    +
    + +## Install Ruby and Vagrant + +The first step is to get Ruby and RubyGems running on Windows. We recommend [RubyInstaller](http://rubyinstaller.org/) for +a quick one-click solution, and this is the solution we support. There are, however, [other methods](http://www.ruby-lang.org/en/downloads/) to getting +Ruby running on windows. + +Once Ruby and RubyGems are installed, install Vagrant with a single command: + +{% highlight bash %} +C:\> gem install vagrant +{% endhighlight %} + +Finally, as with other platforms, you will need to have downloaded and installed [Oracle's Virtualbox](http://www.virtualbox.org/) +for Vagrant to run properly. Vagrant will verify this when it is first run. + +## Good to go! + +With Vagrant installed, you can now follow the remainder of the [getting started guide](/docs/getting-started/index.html) +just like any other Vagrant user and everything should work the same across all +operating systems, including Windows. + +The only difference is `vagrant ssh` and this is covered below: + +#### SSH + +Since SSH is not easy to use/install on the command line under Windows we have included +a [Putty](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) formatted private +key generated from the key pair included with the Vagrant gem. This allows quick and easy SSH +access to all base boxes that leverage that key pair. + +To configure Putty we need 3 things: a user to log on with, the port that Vagrant forwarded for ssh, +and the location of the ppk file. By default the first two will be `vagrant` and `2222`, but there +are many reasons those may be different, especially the port (other vm's services etc). At this point +if you issue `vagrant ssh` from the directory where you created your initial vm you should see +something like the following: + +![No Vagrant SSH On Windows](/images/windows/port_and_ppk_path.jpg) + +It's important to take note of both the port and the .ppk file location. If you've used the Ruby installer, +the above path will be the same for you taking into account the version of the Vagrant gem you have installed. +Moving on, once you've got Putty installed, opening putty.exe will present you with the connection +configuration window. First enter the SSH information and a name for the connection, then open the SSH +configuration sub-tree. + +![Vagrant SSH Info Putty](/images/windows/putty_first_screen.jpg) + +Here in the `Auth` configuration section we'll take the path information provided to us above and locate +the .ppk file via the browse dialog. + +![PPK Selection](/images/windows/ppk_selection.jpg) + +Once you've done that head to the top of the configuration tree, click the `Session` tree item and save +the putty configuration so it will be available for use again later. + +![Save Result](/images/windows/save_result.jpg) + +Last but not least, click the Open button to be presented with a bash prompt inside your new and shiny +Vagrant virtual development environtment! If you've taken the steps above to save the configuration it +should be easy to use and adapt to other virtual environments created with Vagrant. + + diff --git a/docs/getting-started/ssh.md b/docs/getting-started/ssh.md index f59020e88..70b1f4f0c 100644 --- a/docs/getting-started/ssh.md +++ b/docs/getting-started/ssh.md @@ -23,6 +23,19 @@ Last login: Fri Mar 5 23:21:47 2010 from 10.0.2.2 vagrant@vagrantbase:~$ {% endhighlight %} +
    +

    Using Microsoft Windows?

    +

    + SSH is not easy to install or use from the Windows command-line. Instead, + Vagrant provides you with a ppk file which can be used with + PuTTY to + connect to your virtual environments. +

    +

    + Read more about this issue on the Windows setup page. +

    +
    + ## Accessing the Project Files Vagrant bridges your application with the virtual environment by using a diff --git a/docs/getting-started/windows.md b/docs/getting-started/windows.md deleted file mode 100644 index eac45e71a..000000000 --- a/docs/getting-started/windows.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -layout: getting_started -title: Windows ---- -# Windows - -
    -

    Windows Support

    -

    - Windows support is a recent addition to vagrant so if you do experience trouble - or find this section hard to follow, please see the support page - and let us know so we can help you. Our goal is to make Vagrant the best tool - for the job on as many platforms as possible. -

    -

    - All Windows testing has been performed from the vanilla Windows XP command prompt. Cygwin support - is planned but Vista, and Windows 7 testing will have to be a community effort. If you are interested in testing the latest updates please checkout the github page. -

    -
    - -## Assumptions - -The following assumes you have installed Ruby 1.8.6 or greater (see [here](http://www.ruby-lang.org/en/downloads/), in the Ruby on Windows section) with RubyGems and issued the following from a command prompt: - -{% highlight bash %} -C:\> gem install vagrant -C:\> gem install win32console -{% endhighlight %} - -Also, as with other platforms, you will need to have downloaded, installed, and opened [Oracle's Virtualbox](http://www.virtualbox.org/) at least once to generate the necessary configuration files for it, and vagrant, to run properly. - -## Post Installation - -After you have completed the above there are a few more important Windows specific configuration items to handle. - -### Adding VBoxManage to Your Path - -Vagrant, and the virtualbox gem on which it relies, require that the VBoxManage utility is present in your Windows path. When VirtualBox is installed on Windows it doesn't add the utility to the Windows path automatically so you'll need to do that yourself. By default the utility is installed into 'C:\Program Files\Sun\Virtual Box'. If you've installed VirtualBox to a different location you'll need to use that directory when adding it to the path. - -![Copying MAC Address](/images/windows/vbox_manage_default_location.jpg) - -You can add this or other folders to the Windows XP path by taking the following steps. First click Start, right click My Computer and select Properties. Select the Advanced tab in the window that pops up and find the Environment Variables button - -![Environment Variables Button](/images/windows/environment_variables_button.jpg) - -In the next window locate the System Variables list and find the Path variable. Click edit. - -![Edit Path](/images/windows/edit_path.jpg) - -Select the Variable value field and make your way to the end of the dialog to append the path that contains your VirtualBox install and the VBoxManage executable. Make sure to separate each path you add with a semi-colon. - -![Alter Path](/images/windows/alter_path.jpg) - -You can verify that VBoxManage has been made available by opening a command prompt and testing with `VBoxManage`. You should see the help listing for the tool. You can now continue with the installation of a base box and creation of your first Vagrant virtual machine. - -{% highlight bash %} -C:\ > vagrant box add base http://files.vagrantup.com/base.box -C:\ > cd MyProjectDir -C:\ MyProjectDir> vagrant init -C:\ MyProjectDir> vagrant up -{% endhighlight %} - -After this completes you'll need to move onto the following section to connect to your VM. - -### Putty - -Since SSH is not easy to use/install on the command line under Windows we have included a [Putty](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) formatted private key generated from the key pair included with the Vagrant gem. This allows quick and easy SSH access to all Base Boxes that leverage that key pair. - -To configure Putty we need 3 things: a user to log on with, the port that Vagrant forwarded for ssh, and the location of the ppk file. By default the first two will be `vagrant` and 2222, but there are many reasons those may be different, especially the port (other vm's services etc). At this point if you issue `vagrant ssh` from the directory where you created your initial vm you should see something like the following: - -![No Vagrant SSH On Windows](/images/windows/port_and_ppk_path.jpg) - -It's important to take note of both the port and the .ppk file location. If you've used the Ruby 1.8.6 installer, the above path will be the same for you taking into account the version of the Vagrant gem you have installed. Moving on, once you've got Putty installed, opening putty.exe will present you with the connection configuration window. First enter the SSH information and a name for the connection, then open the SSH configuration sub-tree. - -![Vagrant SSH Info Putty](/images/windows/putty_first_screen.jpg) - -Here in the `Auth` configuration section we'll take the path information provided to us above and locate the .ppk file via the browse dialog. - -![PPK Selection](/images/windows/ppk_selection.jpg) - -Once you've done that head to the top of the configuration tree, click the `Session` tree item and save the putty configuration so it will be available for use again later. - -![Save Result](/images/windows/save_result.jpg) - -Last but not least, click the Open button to be presented with a bash prompt inside your new and shiny Vagrant virtual development environtment! If you've taken the steps above to save the configuration it should be easy to use and adapt to other virtual environments created with Vagrant. - -