There are tons of reasons to do laravel development on Homestead. And though you might be convinced to use it, it is not always very simple to be “up and running” within minutes. Laravel’s official documentation on installing Homestead on Windows and Mac is pretty clear. But sometimes, the process is not as straight forward as shown in the documentation. There are a lot of 3rd party software involved and sometimes they create problems. I will be guiding you through the installation and configuration of Laravel Homestead while preventing the common errors from occurring.
You may already know what Laravel Homestead is and what VirtualBox and Vagrant are. But just in case you don’t know then here is a brief introduction for them.
It is a software which helps you run a different Operating System on top of another Operating System. For example you have Windows installed on your machine and you want to use a Ubuntu on it as well. You can do it through VirtualBox. As the name Implies, it creates a Virtual Box or a Virtual Machine inside which you can install other operating systems. In this case, Windows will be your Host OS while Ubuntu will be your Guest OS.
Vagrant is a utility which help us automatically manage Virtual Machines inside Virtual Box. It also help us to ship our software to others or even to the production server with same environment in which we have coded it. Most of Php developers uses Windows or Mac to code on. The main problem with these OSs is that when we ship our software to a Linux environment, it breaks. Vagrant help us ship the software along the environment in an file format known as box e.g Homestead.box
Homestead is a group of software and commands for Vagrant. The official list of what’s included in it can be found here. It automatizes and facilitates the installation of required software for a Virtual Server like Ubuntu, Nginx, MySQL etc.
In short, by combining VirtualBox, Vagrant and Laravel Homestead, one will be able to provide a production environment to Laravel inside Windows or Mac. So you can have all your favorite apps and software of your favorite OS along with the benefit of having a full fledged production level server running Ubuntu and Nginx. Now follow the following steps to get Laravel Homestead up on Windows.
Step 1: Downloading Files
The first step is getting the required software for Homestead. I used VirtualBox and as it is free, I am pretty sure most of you guys will be using it too. Download the VirtualBox from here for Windows (click on the link for windows in the first paragraph). After downloading that, we need to download Vagrant from here. If you have slow internet connection, you will need to download the Laravel Homestead box manually. It is more than 1 Gb in size and on slow connections, the experience can really get very annoying. I will cover that when Installing the Homestead box Later.
Step 2: Install VirtualBox and Vagrant
VirtualBox comes with its own installer which makes installation of VirtualBox very easy but problems may arise. There are a lot of reasons but some common ones are:
- Virtualization might not be enabled on your system
- There can be driver conflicts
- Some other programs specially Kaspersky anti-virus might cause problem
Enabling virtualization will need its own tutorial. For Driver conflicts, your best bet will be do disable the USB driver in the second step of installation. Click the Box to the left of “VirtualBox USB Support” as shown in the figure below. It will disable installation of USB drivers. (USB drivers usually terminate the installation without any specific error)
For the rest of steps, just click “Next” and “Yes”. Make sure that the VirtualBox is installed in the default Program Files directory so that you do not have to configure Vagrant for the path to VirtualBox.
Installation of Vagrant is even more easy. Just double click the installer and proceed with the steps provided. The installation will go smoothly. After that, open the command line utility of windows by searching for cmd in the start menu. Then type the following command in CMD
If Vagrant is successfully installed then, it will display the version number of vagrant.
Step 3: Installing Vagrant Homestead Box
Homestead Box is the a compressed archive which contains all the required software for the Virtual Machine. I will mention two methods of downloading and installing the Homestead Box. The choice to choose one depends on your internet connection speed and reliability.
Fast internet Connection:
If your internet connection is fast enough and is reliable then download vagrant by the officially provided command. It will download the homestead directly. Run the following command in CMD.
vagrant box add laravel/homestead
After running the above command, you will see Vagrant downloading the homestead box with estimated completion time.
- Downloading Homestead Box
Downloading Homestead box manually on slow connection will save you a lot of annoyance. Vagrant disconnects frequently after downloading some part of the file and will start downloading from start every time. To get around this problem, follow the following instructions.
- Download the latest Homestead Box manually by going to this URL: https://atlas.hashicorp.com/laravel/boxes/homestead
/versions/1.1.0/providers/virtualbox.box. Note the bold version number (1.1.0), you will have to change it to the latest version of Homestead. Current version of Homestead can be found here.
- The downloaded file is usually of different name which is “hc-download” most of the time. Edit its name to virtualbox.box
- Run the following command in CMD:
1vagrant box add laravel/homestead file:///Path/to/the/virtualbox.box
- If you have downloaded the virtualbox.box to Windows default “Downloads” folder then your path will be like this “C:\Users\YourUserName\Downloads”. Note that you will have to replace the bold “YourUserName” to your own username. Also don’t forget to prepend “file:///” to your path.
- Now you need to add a metadata_url file to your box’s folder. You can download this file from here.
- Move the metadata_url file to C://Users/YourUserName/.vagrant.d/boxes/laravel-VAGRANTSLASH-homestead. In case you have configured a different directory for Vagrant’s storage then you will need to find the boxes directory there
- Inside the laravel-VAGRANTSLASH-homestead directory, rename the directory “0” to the current version which is currently 1.0.1
Step 4: Installing the Laravel Homestead
Up till now, we have downloaded Laravel Homestead Box which is a Ubuntu OS bundled with required software. The Laravel Homestead on other hand, is a bunch of shell commands and configuration. Homestead enables you to access your Laravel App inside a Virtual Machine from your Windows browser. It also helps you automatically share folders between your Guest OS and Host OS.
Proceed by downloading the Laravel Homestead from its GitHub repository here. You will get a zip file, unzip it to “Homestead” directory. Create one if it don’t exist. It will be better if you create that directory in the your root folder so that you can access it easily.
After this, open the command line and navigate to the newly created Homestead directory by using the following command:
cd /d C:/User/YourUserName/Homestead
Replace the path in the above command with the path to the Homestead directory on your computer. Once inside that directory, run the following command:
This will create a file Homestead.yml in a hidden directory named .homestead . It can be found at C:/User/YourUserName/ . As this directory is hidden, so you need to edit the viewing preference of your Windows to show Hidden files and Directories. In the .homestead directory, open the Homestead.yml file. Preferably use your code editor to edit this file as Notepad will cumbersome the file.
Step 5: Configuring the Laravel Homestead
Rest of the configuration is easy. The homstead.yaml is already configured for a default app. I have covered all of the configuration in great details here “Laravel Homestead.YAML Explained A to Z“. I will cover the basics here:
Authorize & Keys
These variables hold the path to ssh keys which are used by Vagrant to ssh into Guest OS. Its not available on windows by default. You will need to generate them and then place them in the path you have specified in Homestead.yaml . You can generate the ssh keys by using 3rd party software. I personally use the official Git client which you can download from Official Repository. After installation, launch the Git Command line and run “ssh-keygen” to generate the ssh keys. After that, you will need to add the path to the ssh executable to the system variables.
Adding Path to SSH Executable to the System
Search “System Properties” and after opening its window, click the “Advance” tab and then click “Environment Variables” at the end of that tab. You will get a new dialogue having two sections. Find the “Path” in the lower section and after marking it, click Edit. You will get a third dialogue box. Click “New” to the right and then add this path “C:\Program Files\Git\usr\bin” . Be careful as you can wipe all the system paths by mistake.
Folder mapping means that your Guest OS and Host OS will share a common folder where you can keep your laravel files. Laravel Homestead configures a a default folder in the home directory of the Host OS. But if you want to change it then just edit the “map” by providing the absolute path to your desired folder. The beauty of folder mapping is that one can edit the code using windows software like PhpStrom while executing the code inside the a virtual environment.
Sites is a configuration array for Nginx. By default configuration, you will have a “homestead.app” pseudo-domain which will point to a folder inside the “shared folder”. Any php code inside that folder will get executed when you will go to homestead.app inside your browser. You should set it to the “public” folder of your laravel app. Set it to “/home/vagrant/Code/Laravel/public” for now as we will be installing laravel in that way.
Step 6: Configuring the Host File of Windows
Your configuration is nearly complete. Now you need to tell windows to look for a specific ip when you enter homestead.app in the browser. Edit it as follow:
- Go to C:\Windows\System32\drivers\etc\hosts
- Open the hosts file with administrative access
- Add the following line to it. You can add it anywhere but for ease, add it at the top of the file.
- If you have problem saving the file, then first copy the Host file to desktop, edit it and then save it.
- After saving move it to the above mentioned path and replace the original one
- Be careful not to save it with any extension like txt etc
Step 7: Rise and Shine Homestead
Open CMD and navigate to Homestead directory. Its the directory where we unzipped the homestead archive from GitHub. Then run the following command.
You will have your Homestead running in no time. Now go to homestead.app in your browser and be ready to get an error. Most probably “No input File Found”. It is because we don’t have laravel app’s “public” folder yet. We will install laravel in the next step.
Step 8: Install Laravel
This is the last step. If you have added the ssh keys in the proper place or have used PUTTY to create them for you then proceed as follow:
- Enter the command “Vagrant ssh” while vagrant is up
- It will connect you to the Ubuntu OS on virtual machine
- Navigate to the shared folder by entering this command in the CMD
- Then run the following command
1composer create-project --prefer-dist laravel/laravel Laravel
- It will install laravel in the Code folder. You will see a Laravel folder inside it.
- Make sure you have already edited the “Sites” configuration inside the homestead.yaml to “/home/vagrant/Code/Laravel/public”
When the composer installs the laravel, then head over to homestead.app in your browser and you should now see a fresh installation of laravel.
You may encounter errors and problems while following the above steps but everyone do. Homestead is very easy to install and configure and after a few minutes of playing around the problems, you will be able to fix it. Let me know in the comments, if I am missing anything in the article or if you are stuck with laravel homestead. I will be publishing more articles on homestead and will like to tailor them to the beginners problems.