homestead

The Mountain in background is “K2”, the second tallest mountain on earth.

Laravel Homestead has changed the way we code and ship our software. A lot of basic configuration is done in Homestead.yaml but Laravel’s official documentation say very less about it. Few blocks of yaml is explained. Which makes it hard to understand the rest of the file especially for the starters. With time, one can understand the whole homestead.yaml but this post will help you time jump and learn it quickly. Before we start exploring homestead.yaml, I will like to start with an overview of “YAML” itself and creation of homestead.yaml file. Jump to the 3rd heading if you want to skip these two.

YAML

YAML first stood for “Yes Another Markup Language” and now it stands for “YAML Ain’t Markup Language” . It can be called as markdown version of JSON. The benefit of it is that it is cross-language compatible but is human readable as well. It has three man data type:

Mapping (hashes / dictionaries / Key,Value)

Sequences (arrays / lists)

Scalars (Strings & Numbers)

The names in the brackets represents there most probable equivalents in other languages. I will explain these terminologies on the way down with homestead.yaml

Generating Homestead.yaml

When you git clone the homestead or download it from the official directory. Then open the command line tool and navigate to the directory where you have downloaded homestead. Now run

1

bash init.sh

It will create homestead.yaml file in the root of user directory. On windows, its located at C:/Users/YourUserName/.homestead. Remeber that homestead box from vagrant and homestead on git hub are two seperate things. Follow this article for more details.

Part 1: Configuration for the Virtual Server

Configuring the Virtual Server

First part of the homestead.yaml deals with the configuration of your virtual server. Like its IP address, its RAM, CPUs and the Virtual Environment provider. Each of the above element is a scalar in YAML (variable is the equivalent name in programming). These scalars contains strings (e.g virtaulbox) or numbers (e.g 2048) . Each of the item is explained below:

IP

This will be the IP address of your virtual server. The IP range of “192.168” is used for internal communication by variety of devices e.g routers and computers on intranet. Homestead.yaml comes pre-configured with 192.168.10.10. After running the Virtual Machine (VM), you will be able to access the it by going to http://192.168.10.10 . If you change it to some other IP let’s say 192.168.50.10 then your virtual machine will be accessible through that IP. You will have to do “Vagrant reload” for the new IP to take its effect.
My advice will be to leave this IP as is and don’t change it unless required. The reason is that so many online tutorials for configuring host and connecting to other posts use this default IP of homestead.yaml. So it will help you apply other’s tutorials conveniently.

Memory:

As basic purpose of Homestead is to streamline the development and production environment. It makes sense to fine tune the resources of your virtual machine to match that of the development environment. Memory will help you control RAM of the virtual machine. The value given by default is in MBs which is 2048 MB or 2 GB. Your hardware will be the limiting factor because a machine having 2 GB of memory cannot provide more than 2 GB to VM.

CPUS:

As its obvious from its name, it controls the number of cpus which your VM will be using. Most of us will be limited to “1” number unless you need to have multiple cpus on your system. Control on number of cores would have been better as most of cpus have multiple cores.

Provider:

It is the last item in this part. It specify the software which we will be using for virtualization. Currently Homestead documentation states VMWare and VirtualBox to be supported providers for virtualization. There is a way to use Windows’ Hyper-V as well. Homestead.yaml is set to use VirtualBox and you don’t need to edit it unless you are using VMWare.

Part 2: SSH in Homestead.YAML

Path to the SSH keys

This is the part which creates problem for beginners when they are done installing all the software for Homestead. Official documentation don’t reveal anything about adding ssh keys. In homestead.YAML, you will find above paths by default which corresponds to a directory at root of user. E.g on windows its located at “C:\Users\YourUserName\.ssh”. .ssh is a hidden folder and you will need to create it through ssh key generators like puttygen, ssh-gen etc. I have covered this part here “Installing Homestead on Windows“.

Now to understand this segment, we need to dive into the SSH and understand it a bit. SSH is a secure protocol to allow administrators to access and manage virtual servers. As Homestead helps us create a virtual server on top of our machine, so we will need to use ssh to access it. There are many other ways to do this but ssh is the most secure. Furthermore, its been used on the production server almost always. So using ssh on a virtual server makes sense with the streamlining motive of homestead.

Parts of SSH:

Homestead uses Key-Based SSH. Which means there are two keys. One is Public Key, while the other is Private Key. Public key is stored on the virtual machine and is used to authorize access to those with private keys. It ends with an extension “.pub” which means public (shown in point number 5 above). The private key is like a password. You will need this key to authenticate to the virtual server. The virtual server will then compare the public and private key and it will let you connect if the keys are right. Point number 6 holds the private key path.

Configuration of SSH keys for Homestead.yaml

For homestead, you just need to place the above 2 keys in the paths provided in homestead.yaml. Of course you can change the location of keys in Homestead.yaml as well. Be sure to use the exact path. Using the root path will help avoid many errors and problems. Tools like puttygen and ssh-gen will automatically place the authorization key (5) and the private key (6) in the default location of homestead.yaml . If error arises in connectivity, then make sure that the keys exists in specified path. To connect to the VM through ssh, simply run “vagrant ssh” in command line tool.

Part 3: Shared Folders and Sites

I think this is the most edited part of homestead.yaml. First off all, let’s explain it in YAML terminology. The folders: and the sites: are mappers. The -map represents sequences ( having a dash “-” at the start). Mappers hold a block of data and in this case they are holding sequences. Now let’s explain it in terms of homestead.

Folders:

Under the folders, you can configure the folders which will be shared between your Guest OS and Host OS. It has two parts. The “map” holds the path to the folder on your Host OS. Host Os is the operating system on which you have installed homestead. Either a Windows or a Mac. By default, homestead.yaml points to “~/Code” which is a folder located in your user folder.

The exact path to that folder is “C:\Users\YourUserName\Code” on windows. The “YourUserName” part means your username on your computer. If you want to change the shared folder on you Host Os to some other folder, just edit the map above. And set it to a new folder by using absolute path. Like if you move it to a folder named “Project” in a “D” partition, then the absolute path will be “D://Project”. YAML is case sensitive so pay attention to the case as well as the spellings.

The “to” has a value set to the path of folder on Guest OS. In this case, Guest OS is Ubuntu. What this means is that anything you add/edit to “Code” folder on your Host OS will be added to the “/home/vagrant/Code” folder on your Guest OS and vice versa. The benefit is that as your Code folder will be accessible to your Guest OS. So you can easily edit the projects in that folder on your Host OS like by using phpstrom but they will be available to Guest OS. They will run in an isolated environment when executed. So we can put it like this:

-map: Path to the folder on your Host OS where you want to place shared code e.g Laravel

to: Path to the folder on your Guest OS which will share the files with the above mentioned folder.

You can add multiple shared folders to homestead.yaml. The method is the same as adding sites as shown below.

Sites:

The sites helps you name your individual projects so that you can access them through a pseudo domain like homestead.app instead of localhost/laravel. It sets the configuration for nginx. The “map” tells the nginx to listen for that pseudo domain. And the “to” tells the nginx where to look for files on recival of a request through that pseudo domain. In the above screenshot of homestead.yaml we have default settings for one site. It’s psuedo domain name is homestead.app. And the default “to” is set to “/home/vagrant/Code/Laravel/public”. The later one is the path to a sub folder in your shared folder “Code”. It is created when you install laravel in the Code directory through composer.

Now when the VM is up and you open your browser, going to homestead.app will give you a default laravel page. If you don’t have Laravel then you will get a “File Not Found” error. It happens after first time installation.

Another thing which you can do with the sites is that you can add more sites. Example is as follow.

1

2

3

4

5

6

7

sites:

- map: laravel.app

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

- map: open.app

to: /home/vagrant/Code/opensource

- map: client.project

to: /home/vagrant/Code/projects

You can see that I have added three sites to the homestead.yaml file. So by specifying a map and a path for that map, you can add as many sites as you want. And you can open them with your custom pseudo domain name in your browser. But there is one other step you need to do for this to take effect, changing the Host file.

Host:

The host file will redirect the requests for your pseudo domains (homestead.app, open.app, client.project) to the IP that you will specify. Remember the first part? Where we sat an IP for the Virtual Machine. Now we need to set that IP for the above Pseudo Domains in the Host File of Host OS. On Mac and Linux, this file is located at /etc/hosts. On Windows, it is located at C:\Windows\System32\drivers\etc\hosts. Edit this file in a text editor and add the following lines to it.

1

2

3

4

5

6

#if you are using the default pseudo name in the map

192.168.10.10homestead.app

#add one for each pseudo domain you add

192.168.10.10open.app

192.168.10.10project.app

If you have changed your IP in the first section, then use that new IP here. For every pseudo domain, you will have to add an entry like above in the Host file. The whole story of Host and Sites map can be summarized by concluding that the Host File tells your Computer where to look for the pseudo names you have provided. While the “sites” map in homestead.yaml file tells the nginx to look for in these folder for these pseudo domains.

Remember that after adding sites to homestead.yaml, you will have to re-provision the Vagrant. Type “vagrant reload —provision” and press enter in command line.

Part 4: Databases and Ports

For most of the part, you will never need to edit the database map. It contains the name of the default database. Once the vagrant is up, you can add as many databases as you want. You can add them through command line or by installing phpmyadmin. The ports map is for exposing more ports if you need to add any. You can specify multiple lists of ports. Each list starts with “-“. The “send” holds the port number. The “to” holds the internal port number where the VM should forward the requests. And Simply the “protocol” specifies the type of protocol you will allow or use on that port.

Points to Remember

The following points are worth remembering as they will help you avoid errors with homestead.yaml or fix them quickly.

“Input file not found” means that your path is not properly configured and nginx can not find the folder.

After adding site or making other changes, run “Vagrant reload –provision” in command line

Don’t forget to add pseudo domains to host file. After adding them, make sure to not save the file with any extension

Make sure the spelling, the case and the symbols all match each other every where.

Most of the time, reloading the vagrant will take away the

I hope that I have covered most parts of homestead.yaml. Let me know if its missing something or you need help.

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.

Introduction

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.

VirtualBox:

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

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

Laravel Homestead

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:

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

1

Vagrant version

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.

1

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

Slow Connection

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.

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:

1

vagrant 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:

1

cd/dC:/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:

1

init.bat

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:

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:

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.

1

192.168.10.10homestead.app

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.

1

vagrant up

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

1

cd~/Vagrant/Code

Then run the following command

1

composer 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.