Installing Homestead for Laravel Development

This is the first in a two-part series about installing Homestead for Laravel development on your computer. The second part of these series focuses on how to use Homestead for more than one Laravel installation in a single box.

While setting up a Homestead Vagrant box is a fairly straight-forward process and there are tons of tutorials for it all around the web starting with Laravel’s own documentation web site (Laravel Docs), using the same Homestead box for multiple (and similar) Laravel installations is rather tricky – and there are few resources on this topic. And when I say “similar”, I mean other Laravel instances which are using the same PHP version and configuration and the same database versions that will share the resources and configuration of the given virtual machine, and different Laravel framework versions can still be considered similar – at least for Laravel versions later than 5.5.

Although Homestead is not the only option for a local Laravel development environment with alternatives such as Valet on the Mac (since Laravel v5.2), and Laragon on Windows, Homestead is especially favorable because it gives you virtually all the software components you will need in an isolated web development environment.

Included Software with Homestead

Optional Software You can Easily Install on Homestead

Installation & Setup

First Steps

Before launching your Homestead environment, you must have one of VirtualBox 6.x, VMWare, Parallels or Hyper-V installed. You also need Vagrant. All of these software packages provide easy-to-use visual installers for all popular operating systems.

To use the VMware provider, you will need to purchase both VMware Fusion / Workstation and the VMware Vagrant plug-in. Though it is not free, VMware can provide faster shared folder performance out of the box. A valid activated license of VMware Fusion / Workstation is required for this option, otherwise you will get stuck while working with the Vagrant box.

To use the Parallels provider, you will need to install Parallels Vagrant plug-in. It is free of charge.

Because of Vagrant limitations, The Hyper-V provider ignores all networking settings.

You will also need PHP Composer so make sure it is installed on your computer as well. And for Composer to work, you also need PHP installed locally – preferably one whose version matches

In this tutorial, I will assume you are using Virtual Box 6 which requires no extra configuration.

Installing The Homestead Vagrant Box

Once VirtualBox / VMware and Vagrant have been installed, you should add the laravel/homestead box to your Vagrant installation using the following command in your terminal.

vagrant box add laravel/homestead --box-version 8.1.0

I’m explicitly specifying version 8.1.0 here, as too new versions may give you too many experimental features (and breaking changes) as opposed to more familiar ones. (Homestead periodically issues “alpha” / “beta” boxes for testing)  If this command fails, make sure your Vagrant installation is up to date. After a successful execution of the command, it will take a few minutes to download the box, depending on your Internet connection speed.

You maybe prompted in the command line to choose a provider between 1) Hyper-v, 2) Parallels, 3) VirtualBox, 4) VMware_desktop . If you choose any other than option 3 which is VirtualBox, you will need to edit Homestead.yaml file after the Homestead Vagrant box is downloaded and specify whichever other option you have selected, or your box will not work. (I still recommend 3-virtual box).

Installing Homestead

In this tutorial (part 1 of the series), I documented instructions to install Homestead directly into your first Laravel project to use with Homestead, after the next paragraph, and in part 2, you can learn what exactly to do step-by-step to add a second project to the same Homestead box.

You could as well install Homestead by cloning the repository onto your host machine, following the instructions on the related page of the official Laravel documentation. If you choose that path, you can then refer to part 2 of this tutorial to add a second project to the same Homestead box especially in the event of finding their instructions for per project installation too confusing there.

Your First Laravel Project in Homestead

If you do not already have a Laravel project, you can create one executing

laravel new yourprojectname

or

composer create-project --prefer-dist laravel/laravel yourprojectname

After that, you should see several lines of console log the last of which should be something similar to: “Application key set successfully”. Once you see this and get back the prompt, or if you already have a Laravel project type the following and then hit Enter.

cd yourprojectname

then

composer require laravel/homestead --dev

Once Homestead has been installed, use the make command to generate the Vagrantfile and Homestead.yaml file in your project root. The make command will automatically configure the sites and folders directives in the Homestead.yaml file.

Mac / Linux:

php vendor/bin/homestead make

Windows:

vendor\\bin\\homestead make

Next, run the vagrant up command in your terminal and access your project at http://homestead.test in your browser. Remember, you will still need to add an /etc/hosts file entry for homestead.test or the domain of your choice if you are not using automatic hostname resolution.

Finally, unless you already know how to get into the box, just type in the following followed by Enter/Return key:

vagrant ssh

And when inside, go to the conventional code directory with:

cd code

to get to your Laravel directory where you can run

artisan

commands.

This concludes part 1 of this tutorial series on Homestead set-up. In part 2, I explain how to move the contents of the code directory inside a subdirectory named after your project, one more level deep, so that you can have multiple project directories under /code/.