How to setup Laravel Homestead in
Windows

by
JBorbón 17.
March 2017 PHP 8

Developing
with PHP under Windows can be a real pain. Sure there are applications like WAMP
or XAMPP that include the stack you need, but in the end you are not emulating
the environment where your live application is very likely to run:
Linux.

Laravel
Homestead is a great tool to setup your PHP development environment, but it can
be a little confusing to configure and slow in Windows. But fear not, in this
tutorial you’ll learn how to setup Laravel homestead for your PHP
projects.

Installing the software

The
first thing to do is download and install the following software:

VirtualBox for Windows 5.1.14 –
this is what manages and helps emulate a guest OS (Linux, in our case) inside a
host OS (Windows). I recommend this particular version because newer ones would
have problems with folder synchronization.
Vagrant installer for Windows –
this is a command line tool that runs on top of virtualization software such as
VirtualBox or VMWare. It also gives us some other nice features like file sync
between our guest and host OS.
Git for
Windows – we will
need this so we can clone the Laravel Homestead repository from Github, but more
important, it comes with a terminal emulator which will come in
handy.

Note: be sure to install VirtualBox first, since
Vagrant depends on it.

Adjusting VirtualBox and Vagrant

The
next step is to make some tweaks to VirtualBox and Vagrant. We need to do this
because, by default, both tools store data in the same drive where they were
installed (tipically the C drive). The thing with virtual machines is they can
take up a lot of space, so they can eat up your main drive’s storage very
quickly.

First
we’ll change the storage path in Virtual Box, since it’s pretty straightforward.
You now should have a program called Oracle
VM VirtualBox installed. Open it and then go
to File >
Preferences. A new dialog will open where you can change the folder
next to the option that reads Default
Machine Folder. Click the dropdown and choose Other…. Here you can choose the new
folder for VirtualBox to store data. For example, I have a partition called D
and I chose a path on that drive.

Now
we’ll do the same for Vagrant. By default the path where data related to virtual
machines is stored is C:\Users\YourUser\.vagrant.d so I
recommend changing it to a different drive. This can be done with environment
variables. We need to create a variable called VAGRANT_HOME and point it to our desired location.

Open
the control panel and search for the word environment.
From the results choose the one that says edit
environment variables for your account.

On
the new dialog that appears, click the New… button.

Here
you will create the new variable. Enter VAGRANT_HOME as the value for the field
named Variable
name. For the field named Variable
value enter the path of your choice. In my case I
used the path D:\VM\Vagrant

Click OK in
both New User
Variable and Environment
Variables dialogs to save changes.

Getting the Homestead image

Ok,
so now we have the basic blocks for our setup, so what role Homestead plays
then? Well, VirtualBox and Vagrant allows us to emulate the environment, but we
can say these tools only manage and run the virtual machine. We still need an
image of the machine and something that installs the required tools so that we
don’t have to it manually. That’s where Homestead comes in!

First
we need to download the OS for the guest machine. Laravel homestead already has
an image for this. The latest version at this time comes with Ubuntu 16.04. To
install it open Git Bash (the terminal emulator that comes with Git for Windows)
and execute the following command:

1	vagrant box add laravel/homestead

This
will show the following message asking you to choose your virtualization
provider. Enter the number that corresponds to VirtualBox and press
Enter:

The
OS will start downloading. This can take some minutes depending on your internet
connection. Once it finishes downloading a message will appear saying the box
was successfully added.

Getting the Homestead repository

So
we have the guest OS, but it doesn’t have PHP or a webserver installed. For that
we need the Homestead repository, which has the config files and scripts that
take care of those things.

Open Git Bash and cd into
a directory of your choice (tipically your home directory) and clone the
Homestead repository:

cd ~

git clone https://github.com/laravel/homestead.git Homestead

Now
cd into the newly created Homestead directory and initialize the homestead
config:

cd Homestead

bash init.sh

This
will create a configuration file called Homestead.yaml in this directory. We’ll get back to this file
shortly.

Creating a SSH key

Thanks
to Vagrant folder synchronization we’ll be able to edit our project files in the
host machine (Windows) and they will be reflected into the guest machine. But
for other tasks such as running migrations and other commands it will be
necessary to log into the guest via the terminal. For this we’ll need a SSH key.
If you already have one or more you can skip this step.

Once
again, Git
Bash will ease things for us in Windows. Instead of
using a program to create a key and another one to connect to the guest, we can
do all that with this terminal emulator.

To
create a new SSH key enter the following command:

1	ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

A
message like this will appear

1	Generating public/private rsa key pair.

And
then a prompt for a path to store the new key. Simply hit Enter:

1	Enter a file in which to save the key (/c/Users/you/.ssh/id_rsa):

Then
you will be asked for a passphrase twice. This is recommended for security
purposes, but for local development you can leave it empty and just hit Enter
both times:

1 2	Enter passphrase (empty for no passphrase): Enter same passphrase again:

Configuring folders and sites

You
should have now a file called Homestead.yaml inside your Homestead folder. This file should like
this:

---

ip: "192.168.10.10"

memory: 2048

cpus: 1

provider: virtualbox

authorize: ~/.ssh/id_rsa.pub

keys:

- ~/.ssh/id_rsa

folders:

- map: ~/Code

to: /home/vagrant/Code

sites:

- map: homestead.app

to: /home/vagrant/Code/Laravel/public

databases:

- homestead

# blackfire:

# - id: foo

# token: bar

# client-id: foo

# client-token: bar

# ports:

# - send: 50000

# to: 5000

# - send: 7777

# to: 777

# protocol: udp

Let’s
see what these settings mean:

ip: the
local ip address the virtual machine will respond to. This ip should be used in
your hosts file since sites configured in Homestead are served from the virtual
machine, instead from the host machine loopback ip (127.0.0.1).
memory:
amount of RAM in megabytes available for the virtual machine. By default set to
2 GB.
cpus:
number of processors on the virtual machine.
provider: the virtualization system to use. By default
configured already for VirtualBox.
authorize: location of our SSH public key. The tilde (~)
shortcut to point to our user’s home folder is recognized here as
well.
keys:
here we specify the path of the private SSH key. Tipically the same name as the
public key but without the .pub extension.
folders:
this is where we specify which folders in Windows should be synchronized with
the virtual machine. - map is tipically the folder where you have or will have
your application code; Homestead by default points to a folder
called Code in your home directory, but you can change it if you
need to. The important thing here is that this folder won’t be created for you,
so if this will be a new folder, you have to create it first. to is
the path where the contents of - map will be copied to. This folder will be created
automatically in the virtual machine.
sites:
this is where you will map the domains of each application you want to run with
Homestead. Each site should have its own - map and to options where - map should contain the name of the domain
and to should point to the site’s root folder in the virtual
machine. By default, Homestead has a domain named homestead.app that points to /home/vagrant/Code/Laravel/public. An important thing to note is that the root of your
sites must be a sub-folder of the path you configured in the folders section. For example, if you configured a path in the
virtual machine at /home/vagrant/Code,
your sites’ root must be inside /home/vagrant/Code
databases: the list of MySQL databases you want Homestead to
create when it boots.

This
is an example of how the folders, sites and databases sections of our configuration file may look:

folders:

- map: ~/Projects

to: /home/vagrant/Code

sites:

- map: onesite.dev

to: /home/vagrant/Code/onesite.dev/public

- map: anothersite.com

to: /home/vagrant/Code/anothersite/public

databases:

- one_db

- another_db

In
this case, the code in the host Windows machine is in a folder
called Projects which is located at the user’s home folder.
The Projects folder contents will be synchronized to the virtual
machine to a folder located at /home/vagrant/Code.
We have two sites: onesite.dev and anothersite.com;
we can see they both point to a subfolder within /home/vagrant/Code/.
We have also listed two databases to create: one_db and another_db.

Booting the virtual machine

To
boot the virtual machine, cd into the Homestead folder and execute the following
command:

1	vagrant up

The
virtual machine will start booting and configuring. This should take some
seconds.

Connecting to the virtual machine

Once
the virtual machine has booted you can ssh into by simply running the following
inside your Homestead folder:

1	vagrant ssh

You
should be shown something like the following, which means you are now inside the
virtual machine:

From
here you can for example connect to MySQL to manage your databases. The user for
the MySQL installation is homestead and the password is secret.

Another
way of managing databases is using a GUI application. I’ll show you a nice app
for Windows called HeidiSQL and how to connect from Windows to the MySQL server
in Homestead.

If
you logged into MySQL in the terminal, enter the exit command to quit MySQL and then again to logout from the
virtual machine:

Connecting to MySQL with HeidiSQL

The
first thing to do is to get the installer of HeidiSQL.
Get it, install it and open the application. You should be presented with a
screen like this:

On
this screen we’ll configure the connection to MySQL. Click
the New button and follow
these steps:

enter a
description for the connection
enter the
connection credentials
- user:
  homestead
- password:
  secret
- port:
  33060
click Save
click Open

A
new window like this will show, the list of databases will differ since I have
created some other ones.

Adding a new Laravel site

The
virtual machine is running and has the tools installed for us to work. We’ll now
setup a new Laravel project. First we need to add the site to
the sites section of the Homestead.yaml file. Let’s call this site mylaravelapp.dev and add a new database as well called mylaravelapp:

sites:

- map: homestead.app

to: /home/vagrant/Code/Laravel/public

- map: mylaravelapp.dev

to: /home/vagrant/Code/mylaravelapp/public

databases:

- homestead

- mylaravelapp

Now
we need to reload the virtual machine and pass a flag so that it “refreshes” the
list of sites and databases and can pick up our new added site. Execute this
command, make sure you are inside your Homestead directory:

1	vagrant reload --provision

The
virtual machine will reboot and create the new database and add a new nginx site
called mylaravelapp.dev:

Once
the virtual machine has finished booting, ssh into the machine, go to the
shared Code folder and create a new Laravel project with
Composer:

vagrant ssh

cd Code

composer create-project laravel/laravel mylaravelapp

This
will clone the Laravel repository and will begin installing Composer
dependencies. This will install the latest Laravel version, which at the time of
writing is 5.4:

Composer
may take a while depending on your internet connection. Once the installation
finishes we need to open our Windows hosts file located at C:\Windows\System32\drivers\etc\hosts and
add the following:

1	192.168.10.10 mylaravelapp.dev

It’s very likely that you need to open the file with
Administrator privileges. I open it with notepad but I
use Run as
Admnistrator. Also note that the
ip must match the one configured in the Homestead.yaml
file

Save
the hosts file, open your browser and go to http://mylaravelapp.dev.
You should be presented with the Laravel welcome page:

Speeding things up

Even
if the Laravel application is showing the welcome page, it’s very possible that
you notice the page doesn’t load as fast as in a local webserver. This is a
problem with Homestead that for some time we just had to deal with, the good
thing is there is a plugin for Vagrant that will allow us to use NFS (network
file system) on Windows (even when the Vagrant site says it’s simply not
supported).

To
install the plugin simply execute the following command in Git Bash:

1	vagrant plugin install vagrant-winnfsd

The
plugin should take a couple of seconds to install.

Now
there’s only small change we need to do in Homestead.yaml to enable NFS. Add the following to
the folders section in the file:

folders:

- map: ~/Projects

to: /home/vagrant/Code

type: "nfs"

mount_options: ['nolock,vers=3,udp,noatime']

Finally,
re-provision the virtual machine so that it picks up the new options:

1	vagrant reload --provision

And
that’s it, you should notice faster page loads now.

Notice
that when connecting to MySQL from HeidiSQL we used port 33060, this is because
Homestead redirects some of the ports. We did this when connecting from the host
machine, but any configuration in your .env file should use the standard port for MySQL 3306
because your application runs inside the virtual machine, the same goes for the
MySQL host, it would use the loopback ip 127.0.0.1.

And
that’s how we reach the end of the tutorial. I really hope you find it useful
for setting up a development environment for PHP.