Installing and Configuring Homestead 2.0 for Laravel 5

  • January 08, 2015

Welcome to the incredibly popular Easy Laravel 5 companion blog. To celebrate the new edition's release (updated for Laravel 5.5!) use the discount code easteregg to receive 20% off the book or book/video package! » Buy the book

PHP is only one of several technologies you'll need to have access to in order to begin building Laravel-driven web sites. Additionally you'll need to install a web server such as Apache or nginx, a database server such as MySQL or PostgreSQL, and often a variety of supplemental technologies such as Redis and Grunt. As you might imagine, it can be quite a challenge to install and configure all of these components, particularly when you'd prefer to be writing code instead of grappling with configuration issues.

In recent years the bar was dramatically lowered with the advent of the virtual machine. A virtual machine is a software-based implementation of a computer that can be run inside the confines of another computer (such as your laptop), or even inside another virtual machine. This is an incredibly useful bit of technology, because you can use a virtual machine to for instance run Ubuntu Linux inside Windows 7, or vice versa. Further, it's possible to create a customized virtual machine image preloaded with a select set of software. This image can then be distributed to fellow developers, who can run the virtual machine and take advantage of the custom software configuration. This is precisely what the Laravel developers have done with Homestead, a Vagrant-based virtual machine which bundles everything you need to get started building Laravel-driven websites.

Homestead is currently based on Ubuntu 14.14, and includes everything you need to get started building Laravel applications, including PHP 5.6, Nginx, MySQL, PostgreSQL and a variety of other useful utilities. It runs flawlessly on OS X, Linux and Windows, and Vagrant configuration is pretty straightforward, meaning in most cases you'll have everything you need to begin working with Laravel in less than 30 minutes.

Installing Homestead

Homestead requires Vagrant and VirtualBox. User-friendly installers are available for all of the common operating systems, including OS X, Linux and Windows. Take a moment now to install Vagrant and VirtualBox. Once complete, open a terminal window and execute the following command:

$ vagrant box add laravel/homestead
==> box: Loading metadata for box 'laravel/homestead'
    box: URL:
==> box: Adding box 'laravel/homestead' (v0.2.2) for provider: virtualbox
    box: Downloading:
==> box: Successfully added box 'laravel/homestead' (v0.2.2) for 'virtualbox'!

This command installs the Homestead box. A box is just a term used to refer to a Vagrant package. Packages are the virtual machine images that contain the operating system and various programs. The Vagrant community maintains a variety of boxes useful for different applications, so check out this list of popular boxes for an idea of what else is available.

Once the box has been added, you'll next want to install the Homestead CLI tool. To do so, you'll use Composer:

$ composer global require "laravel/homestead=~2.0"
Changed current directory to /Users/wjgilmore/.composer
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing symfony/process (v2.6.3)
    Downloading: 100%

  - Installing laravel/homestead (v2.0.8)
    Downloading: 100%

Writing lock file
Generating autoload files

After this command has completed, make sure your ~/.composer/vendor/bin directory is available within your system PATH. This is because the laravel/homestead package includes a command-line utility (named homestead) which you'll use to create your Homestead configuration directory:

$ homestead init
Creating Homestead.yaml file... ok
Homestead.yaml file created at: /Users/wjgilmore/.homestead/Homestead.yaml

Next you'll want to configure the project directory that you'll share with the virtual machine. Doing so requires you to identify the location of your public SSH key, because key-based encryption is used to securely share this directory. If you don't already have an SSH key and are running Windows, this SiteGround tutorial offers a succinct set of steps. If you're running Linux or OS X, nixCraft offers a solid tutorial.

You'll need to identify the location of your public SSH key in the .homestead directory's Homestead.yaml file. Open this file and locate the following line:

authorize: ~/.ssh/

If you're running Linux or OS X, then you probably don't have to make any changes to this line because SSH keys are conventionally stored in a directory named .ssh found in your home directory. If you're running Windows then you'll need to update this line to conform to Windows' path syntax:

authorize: c:/Users/wjgilmore/.ssh/

If you're running Linux or OS X and aren't using the conventional SSH key location, or are running Windows you'll also need to modify keys accordingly. For instance Windows users would have to update this section to look something like this:

    - c:/Users/wjgilmore/.ssh/id_rsa

Next you'll need to modify the Homestead.yaml file's folders list to identify the location of your Laravel project (which we'll create a bit later in this chapter). The two relevant Homestead.yaml settings are folders and sites, which by default look like this:

    - map: ~/Code
      to: /home/vagrant/Code

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

It's this particular step that tends to confuse most Homestead beginners, so pay close attention to the following description. The folders object's map attribute identifies the location in which your Laravel project will be located. The default value is ~/Code, meaning Homestead expects your project to reside in a directory named Code found in your home directory. You're free to change this to any location you please, keeping in mind for the purposes of this introduction the directory must be your Laravel project's root directory (why this is important will become apparent in a moment). The folders object's to attribute identifies the location on the virtual machine that will mirror the contents of the directory defined by the map key, thereby making the contents of your local directory available to the virtual machine.

The sites object's map attribute defines the domain name used to access the Laravel application via the browser. Leave this untouched for now. Finally, the sites object's to attribute defines the Laravel project's root web directory, which is /public by default. This isn't just some contrived setting; not only is /public the directory you would need to configure when setting up a web server to serve a Laravel application, but /home/vagrant/Code/Laravel/public is also the directory that Homestead's nginx web server has been configured to use! This means that the path defined by the folders map attribute must contain a directory named Laravel, and inside that a directory named public. If you do not do this you'll receive the dreaded 404 error when attempting to access the application via your browser.

If this explanation is clear as mud, let's clarify with an example. Begin by setting the folders object's map attribute to any path you please, likely somewhere within the directory where you tend to manage your various software projects. For instance, mine is currently set like this:

    - map: /Users/wjgilmore/Software/
    - to: /home/vagrant/Code

Next, create a directory named Laravel inside the directory identified by the map attribute, and inside it create a directory named public. Create a file named index.php inside the public directory, adding the following contents to it:

<?php echo "Hello from Homestead!"; ?>

Save these changes, and then run the following command:

$ homestead up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'laravel/homestead'...
==> default: Matching MAC address for NAT networking...
==> default: Checking if box 'laravel/homestead' is up to date...
==> default: Forwarding ports...
default: 80 => 8000 (adapter 1)
default: 443 => 44300 (adapter 1)
default: 3306 => 33060 (adapter 1)
default: 5432 => 54320 (adapter 1)
default: 22 => 2222 (adapter 1)

Your Homestead virtual machine is up and running! Open a browser and navigate to the URL and you should see Hello from Homestead!. Note the use of the 8000 port in the URL. This is because the Homestead virtual machine forwards several key ports to non-standard port numbers, allowing you to continue using the standard ports locally. I've included the list of forwarded ports in the debug output that followed the vagrant up command. As you can see, port 80 (for HTTP) forwards to 8000, port 3306 (for MySQL) forwards to 33060, port 5432 (for PostgreSQL) forwards to 54321, and port 22 (for SSH) forwards to 2222.

If the virtual machine did not start, or if you do not see Hello from Homestead! when accessing, then double-check your Homestead.yaml file, ensuring all of the paths are properly set.

Remember, we just created the Laravel/public directory to confirm Homestead is properly configured and able to serve files found in our local development directory. You should subsequently delete this directory as it will be created automatically when we generate the book theme project in the section, "Creating the TODOParrot Application".

Incidentally, if you'd like to shut down the virtual machine you can do so using the following command:

$ homestead destroy

SSH'ing Into Your Virtual Machine

Because Homestead is a virtual machine running Ubuntu, you can SSH into it just as you would any other server. For instance you might wish to tinker with the nginx or MySQL configuration files, install additional software, or make other adjustments to the virtual machine environment. You can SSH into the virtual machine using the ssh command if you're running Linux or OS X, or using a variety of SSH clients if you're running Windows (My favorite Windows SSH client is PuTTY:

$ ssh vagrant@ -p 2222
Welcome to Ubuntu 14.04.1 LTS (GNU/Linux 3.13.0-30-generic x86_64)

 * Documentation:

  System information as of Thu Jan  8 00:57:20 UTC 2015

  System load:  0.96              Processes:           104
  Usage of /:   5.0% of 39.34GB   Users logged in:     0
  Memory usage: 28%               IP address for eth0:
  Swap usage:   0%                IP address for eth1:

  Graph this data and manage this system at:

  Get cloud support with Ubuntu Advantage Cloud Guest:

Last login: Fri Dec 19 15:01:15 2014 from

You'll be logged in as the user vagrant, and if you list this user's home directory contents you'll see the Code directory defined in the Homestead.yaml file:

vagrant@homestead:~$ ls

If you're new to Linux be sure to spend some time nosing around Ubuntu! This is a perfect opportunity to get familiar with the Linux operating system without any fear of doing serious damage to a server because if something happens to break you can always reinstall the virtual machine!

Creating Your Laravel 5 Application

With Homestead installed you can next create the Laravel 5 application. Because at the time I wrote this Laravel 5 hasn't yet been officially released, we'll need to use Composer (PHP's de facto package management solution) to create a new project using Laravel's development branch. In order to ensure the application is properly served by Homestead, enter the Code directory identified by the homestead.yaml folders object's map attribute, delete the Laravel directory and the test script, and then execute the following command:

$ composer create-project laravel/laravel Laravel dev-develop
Installing laravel/laravel (dev-develop 083db95...dac46617)
  - Installing laravel/laravel (dev-develop develop)
  Cloning develop
Compiling views
Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]? Y
Application key [9UCBk7IDjvAGrkLOUBXw43yYKlymlqE3Y] set successfully.

Once complete, return to your browser, reload, and you should see the default Laravel 5 application splash page!