Homestead.Yaml Explained A to Z

Homestead.Yaml explained

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

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

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

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

homestead-yaml-configuring-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.

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.

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.

  1. “Input file not found” means that your path is not properly configured and nginx can not find the folder.
  2.  After adding site or making other changes, run “Vagrant reload –provision” in command line
  3.  Don’t forget to add pseudo domains to host file. After adding them, make sure to not save the file with any extension
  4. Make sure the spelling, the case and the symbols all match each other every where.
  5. 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.