March 08, 2015

Posted by Sherri Flemings | File under : , , , , , ,
Install Laravel Homestead 2.0 on Windows
I've tried to set up Laravel's Homestead on Windows a few times before. Until now I always gave up because I just ran out of time trying to troubleshoot one error after another on both of my Windows machines. The Homestead setup guide and Laracast videos make it look so freaking easy, but they are not targeting Windows users so it sometimes becomes a very frustrating experience for us... and usually ends with reverting back to your XAMPP or WAMP installation and a promise to try again when you have more time.

I finally had some time to try this again, and although there were a lot of steps and some annoying errors it was actually pretty easy to get going! I know there are some web devs out there who might be intimidated using a command-line, or a virtual machine and some of the error messages you get might have you feeling like you're in way over your head but I wanted to break it down here for you step by step and explain some of the errors to help you get over the initial hurdle of installing Homestead on your Windows machine.

Warning - Before you begin you should verify in your system's BIOS that Intel Virtualization Technology is enabled. It will save you some troubleshooting time if you check now before you get started.

My goal is to install and setup Laravel 5 and Homestead 2.0 on my Windows 8.1 machine. I will be following the same steps on the Laravel install page,  but I will change the paths for Windows and share any errors I came across.

Dependencies:

Before we start make sure you have installed the following software:

Before you install Vagrant - Vagrant uses Ruby, and there is a known issue with Ruby and spaces in paths. My very first mistake was to change the Vagrant install location to %ProgramFiles% like a good Windows citizen and that was a spectacular failure. I opted to install it here on my machine: C:\Tools\Vagrant. I just do my best not to cringe when I see that clutter in the root of my system drive.

Step 1: Open Git Bash

I highly recommend that you use Git Bash as your command-line for the following steps since it will allow us to enter the same commands in the docs without having to manually edit files. If you are also planning to install the vagrant hostsupdater plugin, make sure you open Git Bash as an administrator:


Step 2: Add Vagrant Box

Verify that you have the recommended Vagrant version for Homestead which at the time of this post was Vagrant 1.6

Git Bash

$ vagrant version

Add the Laravel Homestead Box to Vagrant

Git Bash

$ vagrant box add laravel/homestead

This will take several minutes so feel free to grab a coffee or a sandwich depending on your Internet speed.

Step 3: Install HostsUpdater plugin (optional)

The hostsupdater plugin will save you from having to manually update your hosts when you add a new site to your homestead box. Since the Windows hosts file is protected you'll need to make sure you're running Git Bash as an admin (it's not really necessary to be running as admin during this step, but later when you start your homestead box).

Git Bash

$ vagrant plugin install vagrant-hostsupdater

Step 4: Install Homestead

Help: you will see references to your "home" directory, or "~" (tilde) within the Laravel docs. This is *nix vocabulary, the Windows equivalent is the user home path, or the env vars %HOMEDRIVE%%HOMEPATH%. If you are using Git Bash ~ (tilde) maps to the correct directory, however if you're using Windows cmd prompt you should use the above ENV vars to navigate to the home directory.

If you don't have PHP installed on your computer, go to Option 1, otherwise go to Option 2. I recommend Option 1 for most Windows users.

Option 1: You don't have PHP installed on your windows machine

This option assumes you have git installed and already working on your Windows machine. 

Git Bash

# ~ should take you to Windows User Home, %HOMEDRIVE%%HOMEPATH%
# typically it's C:\Users\{username}
$ cd ~
# Copy Homestead into: C:\Users\{username}\Homestead
$ git clone https://github.com/laravel/homestead.git Homestead
    

Once Homestead is installed we'll create the Homestead.yaml configuration file:

Git Bash

# go to the Homestead installation directory
$ cd ~/Homestead
# initialize Homestead configuration file
$ bash init.sh
    

Help - if something goes wrong, or for some reason you're not using Git Bash, you can just copy the files manually. From: C:\Users\{username}\Homestead\src\stubs  to  C:\Users\{username}\.homestead

More Help - You will see references in the docs to homestead commands like homestead init, homestead edit and homestead up. These commands will not be available if you install Homestead from git (Option 1). It's not a big issue, since most of the commands are just wrapping vagrant functionality or providing a shortcut to open the Homestead configuration file in your text editor. I wanted to point this out though since there tends to be some confusion with this.

Go to Step 5

Option 2: You have PHP and Composer already installed

This option will allow you to install the Homestead CLI which provides convenience commands like homestead init or homestead up. If you already have PHP and Composer installed and working on your Windows machine this might be a good option for you, however if you don't already have them installed I strongly recommend following Option 1 above to install Homestead.

Git Bash

$ composer global require "laravel/homestead=~2.0"

To take advantage of the Homestead CLI, make sure to add the Composer /bin directory to your PATH

Help - On Windows you can find the Composer /bin inside your AppData directory: %HOMEDRIVE%%APPDATA% typically this maps to C:\Users\{username}\AppData\Roaming

Git Bash

# initialize Homestead configuration file
$ homestead init

Help - if something goes wrong, or for some reason you're not using Git Bash, you can just copy the files manually. From: C:\Users\{username}\AppData\Roaming\Composer\vendor\laravel\homestead\src\stubs  to  C:\Users\{username}\.homestead

More Help - Although I installed the Homestead CLI using Composer, I actually never use the homestead commands, instead I use the vagrant commands. I just find it less confusing since I have some other vagrant boxes setup now too.

Go to Step 5

Step 5: Generate your SSH Keys

If you are using git, you probably don't need this step. I prefer to use a different SSH key for different tools, so I'm not re-using my git keys for this step. 

My SSH client of choice is Bitvise Tunnelier, and managing keys is super easy with the Keypair Manager included with this client. You can open it by typing 'keypair' into your Windows Start Menu search, or if you have the Bitvise client open you can select the 'User keypair Manager' link on the Login tab.

Run Keypair Manager from Start Menu
Run Keypair Manager from the Bitvise SSH client

After your keys are generated, you can export your public & private keys in OpenSSH format. I exported my keys as homestead_rsa.pub and homestead_rsa.

Export your public and private keys to your .ssh folder

Step 6: Configure your Homestead Box

If you installed the HostsUpdater plugin, you'll need to edit the homestead.rb file  and add an aliases section to your Homestead.yaml file.

%APPDATA%\Composer\vendor\laravel\homestead\scripts\homestead.rb

# Configure A Private Network IP
 ...
# ADD THE NEXT LINE TO CONFIGURE HOSTSUPDATER PLUGIN
config.hostsupdater.aliases = settings["aliases"]
    

Configure your Homestead.yaml file for your environment. Mine looks like this :

%HOMEPATH%\.homestead\Homestead.yaml

---
ip: "192.168.10.10"
memory: 2048
cpus: 1
provider: virtualbox

authorize: ~/.ssh/homestead_rsa.pub

keys:
    - ~/.ssh/homestead_rsa

aliases: ["laravel.app", "stitchcrafter.api"]

folders:
    - map: D:\Data\Code
      to: /home/vagrant/Code

sites:
    - map: laravel.app
      to: /home/vagrant/Code/Laravel/public
    - map: stitchcrafter.api
      to: /home/vagrant/Code/StitchCrafterAPI/public

databases:
    - homestead

variables:
    - key: APP_ENV
      value: local
    

A note about paths - You will notice that I am using the ~ (tilde) character to refer to my Windows HomePath. This should work for you and if you're sharing with a team this is the recommended approach. If you're a lone developer you can stick to hard-coded path if that's what you prefer C:\Users\{username}\.ssh

Ideally I would prefer to stick to the Windows env vars and use %HOMEDRIVE%%HOMEPATH% instead of the ~. Why? Because I don't know if ~ will also work on my Windows machines where the HomePath is not on C drive. Unfortunately Windows env vars are not currently supported.

Step 7: Launch it

So... this is where things sometimes start to unravel, hopefully I can help you get past the error messages so you can get your vagrant homestead box up and running.

A note about the different installation options - cd ~/Homestead will only work if you installed Homestead using git in your home path (Option 1). If you installed it using composer, you can call homestead up without having to be inside the Homestead folder (as long as composer\vendor\bin is part of your PATH). Otherwise you'll have to cd into that long path. In the steps below I follow the path less travelled and use the commands for a Git installation, if you installed with composer please use the commands recommended for that installation type.

Help - Some people are having trouble getting the homestead commands to work properly after installing with composer (Option 2). This is usually a result of not adding composer bin to your PATH. If you prefer to not add it to your path and you're using Git Bash you can take advantage of it and create a .bashrc file in your home path to create an alias (just change the Windows \ to / in the path)

C:\Users\{Username}\.bashrc

alias hs="cd C:/Users/{Username}/AppData/Roaming/Composer/vendor/laravel/homestead"

Now you can just use the hs command to get to the Homestead directory in a composer installation (if you need to).

OK. Let's get this box up and running now...

Git Bash

$ cd ~/Homestead
$ vagrant up

First Error: The first attempt got stuck and kept repeating this error line:
Error: Connection timeout. Retrying...

I opened the VirtualBox GUI to try running the Homestead box from there. This is where I saw what was actually happening. The error popup was helpful, the message started with  VT-x/AMD-V hardware acceleration is not available on your system...

If you see a similar error you will need to enable Intel Virtualization Technology in your BIOS settings. A bit of googling should help you find out how to do that for your specific motherboard.

After enabling virtualization I tried vagrant up again...

Second Error: 
This might look familiar:

Error: Connection timeout. Retrying...

Wait, that's the same error again? I double checked my Homestead.yaml file and realized the path to my private key was wrong.

After correcting my SSH key path I tried vagrant up again...

Third Error: 
... found a tab character that violate intendation while scanning a plain scalar
at line ...

Despite the spelling error (indentation) this error message is fairly obvious. I opened Homestead.yaml in Notepad++ and turned on whitespace and tabs then converted the tabs into spaces.

Alright, now we're good to go! Let's try this again...  vagrant up ...

Oh... what? Another error! Are you kidding me???

Another Error:
.../HostsUpdater.rb 'initialize': Permission denied - C:/Windows.system32/drivers/etc/hosts (Errno::EACCES) ...

You will see this error message if you installed the HostsUpdater plugin and aren't running GitBash as administrator.

Close GitBash and 'run as administrator'...

Git Bash

$ cd ~/Homestead
$ vagrant up

After a minute or so I finally see the words: Machine booted and ready!
Let's SSH in to make sure it's set up properly. I prefer to use the Bitvise SSH console, so as a test I logged in and looked around:

Copy/paste the Host and Port values from the vagrant startup sequence in your console. Above I was verifying that my default Laravel installation was mapped properly.

Step 8: Test your site

If all goes well you should now be able to open a web browser and see your site. My first sites entry looks like this:

Homestead.yaml

sites:
    - map: homestead.app
      to: /home/vagrant/Code/Laravel/public

Let's see if this is working ... I type http://homestead.app in the browser ...

Success!!!

So, was all of this worth it? I think so! Honestly, I doubt I'll get much use out of the Homestead box because it doesn't really mirror my actual server environment, but after dealing with the errors and configuration issues I've become much more confident using Vagrant and VirtualBox. Now I'm setting up my own custom Vagrant box which mirrors my live server environment ... I use virtual machines for mobile and game dev all the time and I'm so excited that I finally took the time to get this working for my web dev environments too.

I hope this helps some wandering Windows user out there. If it does, let me know. I would also like to give a HUGE thanks to Github User Terre Porter whose Laravel.IO thread helped me fill in a few missing pieces and introduced me to the awesome hostsupdater plugin for Vagrant.

Check out this thread on Laracasts for any errors or updates that haven't made it into this post yet: https://laracasts.com/discuss/channels/tips/guide-to-install-homestead-2-on-windows-8

I would also recommend getting familiar with Vagrant commands and don't be afraid to open up some of the Homestead scripts and Homestead source files to poke around and understand what's happening under the hood.

Next up, I'll be integrating this into my Grunt workflow...