How to setup Laravel Homestead in Windows
How to setup Laravel Homestead in Windows
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
- Adjusting VirtualBox and Vagrant
- Getting the Homestead image
- Getting the Homestead repository
- Creating a SSH key
- Configuring folders and sites
- Booting the virtual machine
- Connecting to the virtual machine
- Connecting to MySQL with HeidiSQL
- Adding a new Laravel site
- Speeding things up
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.
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:
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:
Now cd into the newly created Homestead directory and initialize the homestead config:
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:
A message like this will appear
And then a prompt for a path to store the new key. Simply hit Enter:
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:
Configuring folders and sites
You
should have now a file called Homestead.yaml
inside your Homestead folder. This file should like
this:
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 calledCode
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
andto
options where- map
should contain the name of the domain andto
should point to the site’s root folder in the virtual machine. By default, Homestead has a domain namedhomestead.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 thefolders
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:
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:
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:
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
:
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:
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:
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:
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:
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:
Finally, re-provision the virtual machine so that it picks up the new options:
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.