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.
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:
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/bindirectory in your PATH so the
homesteadexecutable is found when you run the
homesteadcommand in your terminal.
Once you have installed the Homestead CLI tool, run the init command to create the
Homestead.yamlfile will be placed in the
~/.homesteaddirectory. If you’re using a Mac or Linux system, you may edit
Homestead.yamlfile by running the homestead edit command in your terminal:
When you look at the list of available commands, it’ll look a lot like what you had available through vagrant:
What’s great now is that you can run any of these from anywhere on your machine by simply typing
You’ll notice a few unique commands, however, that aren’t just maps to the same Vagrant command:
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 creates the
~/.homestead directory and places a skeleton new
Homestead.yaml file in it, as well as
aliases, two additional files that allow you to customize your provisioning.
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 R20;database” config
In addition to
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—
aliases—and one new one,
. .. Homestead.yaml after.sh aliases
From the internal
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).
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 (e.g.
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 upwith 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.
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!