Web
Article

Getting Started with Vagrant on Windows

By Zack Wallace

Vagrant is the hot new buzzword right now on the web, it seems like everyone must be using it.

If you don’t know, you’ll know Vagrant is a program to aid in creating virtual machines via a set of reusable options and configurations. Many people have shared their configurations and scripts via GitHub and elsewhere.

Vagrant is great if you want to spring up servers on-the-fly, to test programs, learn how to use Linux tools, or do stuff in a test environment before trying it on a production system. Do you want to learn to install the PHP Apache MySQL stack from scratch on a new server? Or play with setting up a cache server like Varnish in front of Apache? Even try your hand at Nginx? Vagrant makes things a bit simpler than using VirtualBox directly.

Vagrant logo

Let’s take a look at how to get Vagrant set up on Windows.

Installing the Megabits and Pieces

To get started, go ahead and install these tools:

Create Your Projects

Now that you have it all set up, you can start your first Vagrant project by creating a project folder, which will house the various configurations for each of your VMs. You’ll use the command line to run Vagrant commands from within these folders.

Create your first project folder and call it C:\vm\test\.

Tip: As a Windows user, you can quickly open a command prompt to your project by holding down shift and right-clicking the project folder, then choose “open command window here”.

Using Vagrant

The only commands we need to get servers up and running are vagrant init and vagrant up.

Open a command line and change directories to your test project folder. Then, type vagrant init and a new vagrant file will be created in the current directory. Open and read that file, there are lots of comments you can study. You can set shared folders between guest and host, turn on port forwarding, set the hostname, and more.

Browse the Vagrant Cloud for user-created base boxes you can use. For this example, we’ll use “ubuntu/trusty64” which is the “official” base box for Ubuntu Server 14.04 LTS (Trusty Tahr). Delete the Vagrant file you just created, and type the following:

vagrant init ubuntu/trusty64

This time, if you open the vagrant file, you’ll notice it lists the base box in there.

Vagrant init

Now that you have a vagrant file, you can spin up the VM with this command:

vagrant up

Vagrant will use the configuration in that vagrant file and spin up the VM for you.

Vagrant up

To explain what’s happening here, Vagrant first imports the base box if you don’t already have it. It then checks if your box is up to date. You can see it sets up the SSH forwarding port as “2222” — you’ll need this to use PuTTY.

Lastly, you’ll see it checking for guest additions and mounting the shared folders between host and guest.

These base boxes live in your %userprofile%/.vagrant.d/boxes folder. You can list all installed boxes by typing vagrant box list. You can delete boxes with vagrant box remove box/name

Now I Can Access my Server, Right?

Yes! Kind of!

You see, Vagrant has to be able to log in to the new server and perform additional provision, such as setting the configured IP, port forwarding, folder shares, VirtualBox Guest Additions, etc. In order to do this, all base boxes are required to have the Vagrant public key already installed, along with a user named “vagrant”, with password-less sudo privileges.

Once the VM is created, Vagrant will provide some output, which you should check for errors. See the previous screenshot. Most basebox installs won’t have problems, but advanced scripted provisions can sometimes run into trouble and will have hundreds of lines of text output during the provision process.

The problem we face now is that Windows doesn’t come with an SSH command line client. This means the built-in SSH functions of Vagrant won’t necessarily work for us Windows users. But that’s why we have PuTTY. Type this to get your SSH info:

vagrant ssh-config

It will tell you the IP and SSH port to use and a few other bits of info.

Even though many base boxes are barebones OSes, they do require an SSH server to be installed as one of the requirements of being usable by Vagrant. Most base boxes will have nothing BUT OpenSSH installed.

Open PuTTY, enter the IP and port, give the connection a name, and save it. You can now connect to the new server over SSH with PuTTY. The username is “vagrant” and the password should be “vagrant” as well, but this can be individualized to the base box in special cases. Vagrant doesn’t care about passwords so much, because base boxes are required to have the pubic key installed and Vagrant uses that method rather than a password. And so can we.

Vagrant with PuTTY

Note the different port number than what is in the earlier screenshot. Vagrant will automatically choose another port if the default is taken. All your VMs will get a new port, so be sure to note which VM is which!

Side note: You can install a Windows SSH client, such as Cygwin or MinGW. Even Git comes with an SSH client. Type vagrant ssh and see what happens! Linux and Mac users should already have SSH clients.

Using Public and Private Keys

You can use the same public key Vagrant does and install it to your saved PuTTY connection. However, PuTTY cannot use the OpenSSH style key. This is why we downloaded PuTTYGen, so open that now.

Click “Load” and browse to the %userprofile%/.vagrant.d/ folder and you’ll see the “insecure_public_key” file. Open that.

You can immediately click the “Save Public Key” button. This will create a file with a “.PPK” extension. Name it “insecure_public_key.ppk” to match the other one. You can close PuTTYGen and go back to PuTTY now.

Save public key

In PuTTY, load your connection to the new server or type it in again if you didn’t save it. Then go to Connection->SSH->Auth in the sidebar and click “Browse” to find the private key. You will see the PPK version but not the other one since PuTTY doesn’t use that type. Now be sure to save your configuration so you can keep using it later.

Private key in PuTTY

With that done, the next time you open this connection and type “vagrant” as the user, it will automatically authenticate with the key and you will be logged in without having to type the password.

You can also create your own secure public/private keys with PuTTYGen and replace the vagrant key but that is beyond the scope of this article. You would need to paste the key into the ~/.ssh/authorized_keys file as well as make an edit to the vagrant file.

Additional Notes

The vagrant file is where all configuration takes place. This file is meant to be managed by a version control system, and is how you would share your development setup with a team. If everybody uses the same vagrant file, they’ll get the same VM setup with the same boxes and provisions. Note that scripts can be called external to this file, meaning some complex vagrant projects could have many files and folders.

You can use VirtualBox to see any VMs you have made, but you don’t actually have to open or use VirtualBox at all when using Vagrant. If you make certain changes to the VM from VirtualBox, there’s a chance Vagrant could lose the association to the VM.

The “base” boxes are stored in the %userprofile%/.vagrant.d/boxes folder. These will be used over and over for any projects you create that use the same box.

If you destroy all VMs that use a certain box, this does not delete the box itself.

Vagrant creates a shared folder between your project folder and a folder in your VM which is /vagrant by default. Any files in your C:\vm\test folder will show up in the VM and vice-versa. New shares can be setup in your vagrant file. Often boxes are used as development machines, so a common folder to share is your Apache or Nginx www folder.

You can turn the VM off by using vagrant halt, or suspend it with vagrant suspend. Then turn it on again any time with vagrant up. Type vagrant status to see the current state of the VM.

All commands can be found here.

Additional Security

Because anybody can create base boxes, the Vagrant rules state that they should create a user and password vagrant/vagrant. It also states that it does not expect the root user to have any password i.e., it does not use root nor expect a password for it. It would be good practice, if you feel the need, to know what the default users and password are on the box you choose to install.

The rules also state that Vagrant needs password-less sudo on the vagrant user so that it can perform the setup, so you should be aware of this if you are trying to increase security.

Vagrant sets SSH ports to bind to localhost, so it won’t accept connections from the “outside”. This can be changed if you wanted access to your VM from some other host somewhere else. You would need additional setup to do this.

The insecure public/private keys are used by default. These can be replaced using PuTTYGen.

Next Steps?

Now that you’ve learned how it works, you’ll want to go further. You can find additional boxes apart from Vagrant Cloud, such as http://www.vagrantbox.es. Using a box from another source is as simple as typing vagrant init box/name url where the ‘box/name’ and ‘URL’ will be provided for you.

George Fekete covered how to create your own base box in a previous article.

You can even use DigitalOcean as a provider and deploy droplets using Vagrant.

Automation tools like PuPHPeT and Protobox help you create the provisioning scripts for deploying more full-featured development VMs.

You may have heard of the popular Vagrant box Laravel Homestead which can be used to deploy a development server for Laravel projects. SitePoint’s Bruno Skvorc has built off of Homestead to create what he calls Homestead Improved with some alternate configuration.

There is a box called VVV which not only creates a development box for WordPress devs, but actually sets it up so you can host multiple WordPress sites on one VM. Homestead does the same thing, so that you aren’t using one whole VM for each project you work on. Aleksander Koko wrote about VVV on SitePoint.

The sky’s the limit, so jump in and look around for cool boxes, provisioning scripts, or create your own!

I hope that helps get you started! Let us know in the comments if you finally took the plunge, and how you found it.

  • Daniel Noyola

    Now I now why I couldn’t access my vagrant servers on windows (insecure_public_key)

    • http://www.zacksdomain.com/ Zack Wallace

      Glad it’s sorted out.
      If you wanted, PuTTY can even store the username too, for complete automated logging in, which isn’t a big deal for dev servers I would think. Very convenient.

  • Dave

    I like the idea of Vagrant, but shared folders when the host OS is windows just don’t work properly. Permissions don’t work, symlinks don’t work, long filepaths don’t work, and the shared folder is mounted too late for init / cron tasks.

    • http://www.zacksdomain.com/ Zack Wallace

      I suppose a more advanced Windows/Linux share could be setup manually. Just use SSH/SFTP or keep the built-in file sharing for simple needs. Nothing is perfect!

      • Dave

        SSH doesn’t really work for me as I like to use a GUI editor. And SFTP is a pain if you want to regularly check your work since you have to upload the file each time.

        I’m not sure how to set up a more advanced share that avoids the issues standard shared folders have. Maybe an idea for a follow-up article for you?

        • http://www.bitfalls.com/ Bruno Skvorc

          Just use this and all your problems will be solved, including shared folders: http://www.sitepoint.com/quick-tip-get-homestead-vagrant-vm-running/

          I code with a GUI editor and even have remote debugging set up.

          • Dave

            Hi Bruno

            I’ve now tried your suggestion, but it didn’t solve any of the problems with shared folders. I’m not sure how it could?

          • http://www.bitfalls.com/ Bruno Skvorc

            What exactly is the problem you’re having? I’ve been using this for a while now and never had difficulties, other than with symlinks.

          • Dave

            Permissions don’t work, symlinks don’t work, long filepaths don’t work,
            and the shared folder is mounted too late for init / cron tasks.

          • http://www.bitfalls.com/ Bruno Skvorc

            Long filepaths will always be a problem on Windows, the only workaround I’ve found was putting the VM as close to root of the drive as possible. Lame, I know, but it helps with the apocalyptic evil and incompetence that is NPM. I haven’t had problems with permissions, as long as I manage them from inside the VM. Symlinks work when you launch the VM through an elevated prompt.

          • Dave

            Do you mean setting permissions on files in a shared folder works for you? Or do you just mean that you ensure any folders that contain files you need to set permissions on are stored in the VM image and not in a shared folder?

            While the various issues can be worked around to some extent, I find the issues relating to working fully in a VM to be less than the issues of working in Windows with shared folders.

          • http://www.bitfalls.com/ Bruno Skvorc

            Setting permissions on a shared folder from inside the VM works for me. Once I share a folder, I don’t touch it in windows any more – the only tool allowed to do that is my IDE, everything else is handled inside the VM.

          • Dave

            Weird… For me, when I set permissions on a file that is stored in a shared folder it doesn’t do anything, the permissions stay as they were.

          • blindfish

            I’ve just been struggling with these issues myself trying to build a dev environment running Grunt etc. Have yet to encounter sharing issues… Can’t wait :/

            Long filepaths are definitely an issue with npm on Windoze and I suspect that will bite people with local installations too… So following suggestions I found elsewhere I symlinked node_modules on the host to a folder in the VM (and for good measure bower_components too).

            To do that you need to run the vagrant provision script (usually your first `vagrant up`) as admin (so open command prompt as admin or with elevated user rights). Once the symlink is in place it seems you can run subsequent Vagrant sessions without admin rights.

            For info: If you’re installing Bower and trying to run `bower update` you’ll also run into problems: it doesn’t like running as root and some bright spark has updated it to prompt for user tracking preferences; which essentially breaks any automation. The following command appears to be working for me:

            sudo bower update –allow-root –config.interactive=false

          • blindfish

            Looks like my optimism was ill-founded: my colleague was unable to create symlinks when running on ‘Elevated user rights’; so it has to be admin only :(

  • SimaWB

    The best explanation I’ve read about Vagrant!

  • Ahmed Abdo

    Every time I try to run it using vagrant up I get this:

    E:VagrantQKlzfB>vagrant up
    Bringing machine ‘default’ up with ‘virtualbox’ provider…
    ==> default: Importing base box ‘puphpet/ubuntu1404-x64’…
    ==> default: Matching MAC address for NAT networking…
    ==> default: Checking if box ‘puphpet/ubuntu1404-x64’ is up to date…
    ==> default: There was a problem while downloading the metadata for your box
    ==> default: to check for updates. This is not an error, since it is usually due

    ==> default: to temporary network problems. This is just a warning. The problem
    ==> default: encountered was:
    ==> default:
    ==> default: SSL certificate problem: unable to get local issuer certificate
    ==> default: More details here: http://curl.haxx.se/docs/sslcerts.html
    ==> default:
    ==> default: curl performs SSL certificate verification by default, using a “bun
    dle”
    ==> default: of Certificate Authority (CA) public keys (CA certs). If the defau
    lt
    ==> default: bundle file isn’t adequate, you can specify an alternate file
    ==> default: using the –cacert option.
    ==> default: If this HTTPS server uses a certificate signed by a CA represented
    in
    ==> default: the bundle, the certificate verification probably failed due to a
    ==> default: problem with the certificate (it might be expired, or the name mig
    ht
    ==> default: not match the domain name in the URL).
    ==> default: If you’d like to turn off curl’s verification of the certificate, u
    se
    ==> default: the -k (or –insecure) option.
    ==> default:
    ==> default: If you want to check for box updates, verify your network connectio
    n
    ==> default: is valid and try again.
    ==> default: Setting the name of the VM: QKlzfB_default_1427808840733_46834
    ==> default: Clearing any previously set network interfaces…
    ==> default: Preparing network interfaces based on configuration…
    default: Adapter 1: nat
    default: Adapter 2: hostonly
    ==> default: Forwarding ports…
    default: 22 => 9342 (adapter 1)
    default: 22 => 2222 (adapter 1)
    ==> default: Running ‘pre-boot’ VM customizations…
    ==> default: Booting VM…
    ==> default: Waiting for machine to boot. This may take a few minutes…
    default: SSH address: 127.0.0.1:2222
    default: SSH username: vagrant
    default: SSH auth method: private key
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    default: Warning: Connection timeout. Retrying…
    Timed out while waiting for the machine to boot. This means that
    Vagrant was unable to communicate with the guest machine within
    the configured (“config.vm.boot_timeout” value) time period.

    If you look above, you should be able to see the error(s) that
    Vagrant had when attempting to connect to the machine. These errors
    are usually good hints as to what may be wrong.

    If you’re using a custom box, make sure that networking is properly
    working and you’re able to connect to the machine. It is a common
    problem that networking isn’t setup properly in these boxes.
    Verify that authentication configurations are also setup properly,
    as well.

    If the box appears to be booting properly, you may want to increase
    the timeout (“config.vm.boot_timeout”) value.

    E:VagrantQKlzfB>

    Can you please help me with this ?

    • Chris Kavanagh

      I had the same problem on Windows 8.1 Once I googled it, most people said it was a BIOS issue with turning on the Virtualization feature. So, I went into BIOS (F10 at startup), went into “Security” and there it was. Made sure it was on, and this corrected the problem. . .

  • http://www.zacksdomain.com/ Zack Wallace

    Sorry, I just now saw this reply!

    Since it’s bee a few months, did you get it all sorted out?

    Note that seeing some “Connection timeout” messages is pretty normal because at that point, the server is actually booting up, and if Vagrant tries to access the VM before it’s done loading, it will just time out. I usually see 2 or 3 timeouts before the VM is loaded and Vagrant can access it.

    The other error has something to do with SSL certificates, it gives you the option of trying it in insecure mode with the “-k” switch. You might try that.

  • http://jaykilleen.com/ Jay Killeen

    I think there needs to be a better explanation around ‘vagrant init ubuntu/trusty64’.

    I started this process for the first time with some intermediate development knowledge and I got stuck. A lot of ‘how to’ sites reference the two commands ‘vagrant init’ and ‘vagrant up’ as being the only commands you need without actually explaning the parameters you are sending to these commands.

    I thought ‘ubuntu/trusy64’ was just a vm name or folder name of sorts, not that it was actually going to atlas and getting the specifications to build the box.

    I then went searching for how to spin up a box on VirtualBox and then somehow configure the vagrantfile to point to that box.

    It is all very easy now that I understand that I can’t just ‘vagrant init’ and ‘vagrant up’ to get up and running.

    • http://www.zacksdomain.com/ Zack Wallace

      You’re right, simply typing “vagrant init” only creates a Vagrant file, but it will not have a reference to a particular box to use. That’s why I then had people delete that file and do it again referencing the box before using “vagrant up”.

      “Vagrant up” obviously just starts the box based on the config file as such.

      I did mention the box was being looked up at the Vagrant cloud, sorry I wasn’t more clear explaining that!

      As for building a box in VirtualBox directly and then somehow attaching it to Vagrant, I don’t believe you can even do that. If you’ve figured it out, it’s the long way around!

  • Chris Kavanagh

    Thanks Zack! Man, this helped a lot.

  • http://www.kevinmamaqi.com/ Kevin Mamaqi

    Thank you, really helpful information.

  • byron

    Excelent tutorial! thanks.
    One question:

    you wrote: “…. You would need to paste the key into the ~/.ssh/authorized_keys
    file as well as make an edit to the vagrant file.”

    I have these questions:

    1.- I don’t have in my OS (windows 10) the file “authorized_keys” I search for it in “c:Usersusername.ssh”. Where is it located?

    2.- how will I copied that key?
    2.1.- Must I copy the text that appear in PuTTygen section: key/public key for passing into OpenSSH autorized_key files?
    2.2.- Is it necesary to link it to something?

    3.- My two folders (windows – vagrant) are not synchronized, are they supposed to synchronize?

    4.- What I need to edit inside of vagrantfile?

    thanks for your help

    • byron

      HI every one, for topic 3.- “My tow folders (windows – vagrant) are not synchronized..” the reason is the next:

      I run again vagrant up and I receive this warning:

      The guest additions on this VM do not match the installed version of VirtualBox! In most cases this is fine, but in rare cases it can prevent things such as shared folders from working properly. If you see shared folder errors, please make sure the guest additions within the virtual machine match the version of VirtualBox you have installed on your host and reload your VM.

      Guest Addition Version: 4.3.10
      VirtualBox Version: 5.0

  • Paul McCann

    The insecure public key doesnt seem to work for me if I import it into puttgen. I think its because on startup Vagrant now creates a new key pair. Is this the same insecure key or do I need to look somewhere else and turn a different file into a ppk.

    default: Vagrant insecure key detected. Vagrant will automatically replace
    default: this with a newly generated keypair for better security.

  • Zachary Poe

    I ran into this issue as well. During the vagrant init, the output says it’s skipping the insecure key and generating a new one. When you run ‘vangrant ssh-config’ the output provides a ‘IdentityFile’ and you can load this file into puttygen. If you choose the ‘Save private key’ option, then follow the steps above, you can use this key for your PuTTY session.

    Additionally, in your PuTTY session under Connection -> Data, you can specify an ‘Auto-login username’ to make the ssh connection to the VM a one click step.

  • http://www.zacksdomain.com/ Zack Wallace

    Hi,
    I can only guess a couple possibilities.

    1) The remote file has the problem. If so, try testing with some other options for the box. If all boxes fail, that’s not it.
    2) You have a firewall or antivirus tool blocking the remote connection and stopping the download.

    There is also the remote possibility that Vagrant is somehow corrupt or can’t download due to its file fetching tools. Uninstall/reinstall may fix it, you might even try an older version if it’s just the latest causing it.

  • http://gregordy.info Gregordy

    Very good article, helped me a lot!

    One question though, is “.ppk” not meant to refer a private key file?!
    I had a few doubts when it came to name the key created with the “Save public key” button “thekey.ppk”.

  • M S i N Lund

    Had to give up on this.

    Its just to ridiculously complicated to get working on windows.
    Every single tutorial i have found on vagrant, gets it wrong, an you have to spend forever on step after step, figuring out what you are actually supposed to do to get it working.

    Coming from Windows, thus whole linux-thing just seem like one big horrible kludge with endless headaches to get even the smallest thing working.

    • http://www.zacksdomain.com/ Zack Wallace

      What were your problems?

      People seem to run in to issues if the computer’s BIOS isn’t set up right for virtualization. Or they don’t have the C++ runtime libraries installed. Or something else is up with Windows 8. Or they have a permission issue (try doing things from your user folder, not just in C: for example).

      It is, of course, not supposed to be complicated at all. It’s just, install VirtualBox, install Vagrant, type a couple commands, it just works. Then because Windows doesn’t have an SSH client in the shell, use PuTTY to connect.

      I’m curious where your setup broke down.

      • http://nailson.me Nailson Landim

        Yes it is possible to use Vagrant on Windows, i did on past and worked, but you’ll have a lot of work with provisioners or advanced things like that.

        In fact, is better to use a *nix environment, it’s dead simple, everything works and you save time, and that’s the principle of using vagrant. if you HAVE to use Windows, ok, but you’ll get extra work.

        • http://www.zacksdomain.com/ Zack Wallace

          Maybe extra work, if you need advanced features or features that are home in *nix environments like permissions stuff.

          You’ll get no argument out of me, but really it’s not that bad in Windows for basic needs like website design.

Recommended

Learn Coding Online
Learn Web Development

Start learning web development and design for free with SitePoint Premium!

Instant Website Review

Use Woorank to analyze and optimize your website to improve your website to improve your ranking!

Run a review to see how your site can improve across 70+ metrics!

Get the latest in Front-end, once a week, for free.