Installing Laravel Homestead

Published Apr 11, 2019

Installing Laravel Homestead

Recently I decided to go "full Laravel" with my PHP development. I have a light-weight custom PHP MVC framework that I built a while ago, it's fast but I haven't been keeping it up-to-date. As part of going "full Laravel", I decided to no longer use XAMPP for my Laravel projects and rely strictly on Homestead. Let me take you on my African developers tutorialised journey of this process.

The first thing needed to get started is virtualisation software. Depending on your operating system, you have the option to use VirtualBox, Parallels, HyperV and VMWare. Fortunately, I already had VirtualBox installed, so I had that covered. If you don't have any of these, take pick, install it and you can move on to the next step.

The second thing needed is Vagrant. Vagrant is an development environment deployment system. It allows you to deploy an operating system and software configurations in a consistent and replicatable fashion. This software was new to me, but it was trivial to install. If you don't have it, head over to the website, grab a copy and install it.

After installing Vagrant, you can test out if your installation is working correctly by running:

vagrant --version


Vagrant stores environments in a "box". This holds a copy of the virtual machine image that provides the base system, as well as a Vagrantfile to configure the system on deployment. At this point, we are ready to install the Homestead box. It is also at this point that the African developers journey forks from path others would normally follow.

If you have a speedy internet connection, non-African developers ;), run:

vagrant box add laravel/homestead

According to the Laravel documentation this: "It will take a few minutes to download the box, depending on your Internet connection speed." I thought I had a decent Internet connection but alas, this was not so. I doubt the Vagrant download manager is multithreaded, it reported that I'd need about a day to for the download to complete. All I could think is "There must better alternative to this," and indeed there was.

For African developers, you additionally need a multithreaded download manager. I use uGet, it's free, it gets the job done and it's multi-platform. Feel free to use whatever pleases you, but I'll repeat, a multithreaded download manager is needed. It will save you a lot of time, sometimes there is a rush in Africa.

Head over to:

We need to establish the latest Homestead box version that is currently in release. At the time of writing this, it's 7.2.1. We also want to establish the providers available, providers are synonymous with the virtualisation software in use. My list looked like this:

    virtualbox Hosted by Vagrant Cloud (1.28 GB)
    parallels Hosted by Vagrant Cloud (1.33 GB)
    hyperv Hosted by Vagrant Cloud (1.16 GB)
    vmware_desktop Hosted by Vagrant Cloud (1.31 GB)

Compose the URL to download the appropriate box for your installation:<version-number>/providers/<provider-name>.box

In my case, I needed version 7.2.1 for a VirtualBox installation, so I used:

After the box is downloaded, rename the file to something memorable like the name of your provider. I renamed mine to .

We can now manually install the box by running:

vagrant box add laravel/homestead file:///c:/users/taurai/downloads/

Replace the path as needed.

If everything went well, the box has been installed to /.vagrant.d/boxes/laravel-VAGRANTSLASH-homestead . Run:

// Windows
cd %userprofile%/.vagrant.d/boxes/laravel-VAGRANTSLASH-homestead

// on Linux and OSX
cd ~/.vagrant.d/boxes/laravel-VAGRANTSLASH-homestead

There should be a single directory named 0, that's a zero by the way. Rename this directory to the version number of the box you downloaded. Run:

// Windows
move 0 7.2.1

// on Linux and OSX
mv 0 7.2.1

Next we need to set up the box's metadata:

// Windows, Linux and OSX (make sure not to quote the URL on Windows)
echo > metadata_url

The African developers path now merges with the norm. Despite the longer detour I took, it did yield a great, but not so obvious benefit. I can copy and install the box on any other machine without delays.

I was now ready to install Homestead itself and clone the repository to my host machine. Documentation recommends cloning the repository into a Homestead folder within your directory, as the Homestead box will serve as the host to all of your Laravel projects. On Windows, I wouldn't recommend this, as the is obscure and instead I opted to clone it to my E: drive. The Windows is also easily forgotten when migrating machines, so again, I don't recommend it.

// Windows
git clone E:\Homestead

// on Linux and OSX
git clone ~/Homestead

As per documentation, you should check out a tagged version of Homestead since the master branch may not always be stable. Navigate into the Homestead directory:

cd Homestead

Clone the desired release:

git checkout v8.0.1

Once you have cloned the Homestead repository, run the bash command from the Homestead directory to create the Homestead.yaml configuration file. The Homestead.yaml file will be placed in the Homestead directory:

// Windows

// on Linux and OSX

If you are following this as a tutorial, the process for configuring Homestead can be completed from the Laravel Homestead documentation. I see no benefit in repeating it here. I didn't fully configure my installation till later.

Since I was playing with a shiny new toy, I decided to fire up Homestead and bring up the environment, by runnning:

vagrant up

My vagrant squawked, "Check your Homestead.yaml file, the path to your private key does not exist."

It would seem there is a step left out of the documentation. There is a key that needs to be generated for authentication:

ssh-keygen -t rsa -b 4096 -C ""


I just hit enter at the prompts, then tried again:

vagrant up

The first run took a little while as vagrant prepared (provisioned) the environment, then Homestead was now ready to rumble.

And that's it for my first blog post...

African Developer