When Laravel Homestead first came out, it was a Github repository that included a base Homestead.yaml by default. There was no prescribed place to install it, no global commands for accessing the box, and any time you actually customized your Homestead.yaml file you instantly dirtied your Homestead Github clone, making upgrading difficult.

You can guess where I’m going with this. All of these things are problems no more. The latest version of the Homestead ecosystem has just been released, and it’s moved Homestead into a globally installable Composer package which copies Homestead.yaml (and any other user-editable files) into ~/.homestead on your machine. This way there’s a clear future upgrade path; you get instant global access; and it’s clear where your config file should live.

Installing fresh

As always, the Laravel docs are the best place to go for the fullest installation instructions. But here’s the one section that’s most different from the past, copied directly from the docs:

Installing Homestead

Once the box has been added to your Vagrant installation, you are ready to install the Homestead CLI tool using the Composer global command:

composer global require "laravel/homestead=~2.0"

Make sure to place the ~/.composer/vendor/bin directory in your PATH so the homestead executable is found when you run the homestead command in your terminal.

Once you have installed the Homestead CLI tool, run the init command to create the Homestead.yaml configuration file:

homestead init

The Homestead.yaml file will be placed in the ~/.homestead directory. If you're using a Mac or Linux system, you may edit Homestead.yaml file by running the homestead edit command in your terminal:

homestead edit

Available commands

When you look at the list of available commands, it’ll look a lot like what you had available through vagrant:

• Destroy
• Edit
• Halt
• Init
• Resume
• Up
• Update
• Ssh
• Status
• Suspend

What’s great now is that you can run any of these from anywhere on your machine by simply typing homestead COMMAND.

You’ll notice a few unique commands, however, that aren’t just maps to the same Vagrant command:

Homestead edit

Like you read in the docs, Homestead edit (on Mac and Linux machines) will automatically open up your Homestead.yaml file in your system’s default editor.

Homestead init

Homestead init creates the ~/.homestead directory and places a skeleton new Homestead.yaml file in it, as well as after.sh and aliases, two additional files that allow you to customize your provisioning.

Homestead update

Homestead update runs vagrant box update, so you can update the Homestead machine image—for example, when Taylor adds PHP 5.7, this will be the way to upgrade your Homestead image.

New "database" config

In addition to folders and sites there’s now a databases option in Homestead.yaml that allows you to specify databases for the vagrant box to create when it provisions.

New "after.sh" file

When you get into your new ~/.homestead directory, you’ll see two familiar files—Homestead.yaml and aliases—and one new one, after.sh.

.
..
Homestead.yaml
after.sh
aliases

From the internal after.sh docs:

If you would like to do some extra provisioning you may
add any commands you wish to this file and they will
be run after the Homestead machine is provisioned.

The upgrade path

IMPORTANT: At the time of writing this, I don't know how to upgrade to the new version of Homestead without it just creating a new Homestead box from scratch. You won't lose your old box (you can always access the old way), but your new box will be fresh, not imported from the old one. Do you know how? Please let me know on Twitter: @stauffermatt

Most of you reading this already use Homestead. So, what does the upgrade path look like?

For starters, install it globally and make sure the Composer bin is in your PATH (like above).

Now, run homestead init anywhere in your terminal. You should see the following output:

○ homestead init
Creating Homestead.yaml file... ✔
Homestead.yaml file created at: /Users/mattstauffer/.homestead/Homestead.yaml

If you check out the new ./homestead directory, you’ll see your skeleton config file. Now just copy over your old aliases file and Homestead.yaml file; for example:

cp ~/OldHomesteadDirectory/Homestead.yaml ~/.homestead
cp ~/OldHomesteadDirectory.aliases ~/.homestead

Now add a chunk at the bottom of your Homestead.yaml file that looks like this:

databases:
    - homestead

Now, you should be able to run homestead up from anywhere and see the first provision. Note, like I wrote above: This is creating a new Homestead box from scratch (using your Homestead.yaml file), not importing your old one. So you'll have to re-migrate and -seed your databases, etc.

Caveats: The first time I ran homestead up with the new version, I got a lot of errors. I upgraded my Homestead box (homestead update), and the next time I provisioned I didn't get any errors. I don't know whether the fix was just running it twice, or upgrading the machine image, but either way it all runs fine now.

Concleezy

That's it. Migrating might be a bit of a pain (although this might be a motivation to create better migrations and seeds ;) ), but this is a much cleaner system with a much clearer upgrade path. Much rejoicing!