Using user-customizations.sh in Laravel Homestead
Today, Laravel Homestead maintainer Joe Ferguson tagged version 7.16.0 of the Laravel Homestead library. The announcement tweet includes “Adds support for user-customizations.sh” which, probably doesn’t mean much to anyone who hasn’t followed Pull Request #932 over the last few days. As the person who opened that particular PR, I figured it might be nice to document the motivations:
Just tagged https://t.co/fh7bhjpedx
— LaravelHomestead (@HomesteadDev) September 4, 2018
The goal of Laravel Homestead is to make it as easy as possible for developers to collaborate on projects by providing a sensible, Vagrant-powered development environment; any member of a team can clone the repo, run a few commands, and have an environment that’s identical to every other member of the team.
Technically, Laravel Homestead supports two different installation models: a global installation (where you would have multiple projects running on a single VM), and a per-project installation, where each project runs its own Homestead instance. The latter method can require more resources, but is generally a much better approach for teams working on multiple applications with different configurations and dependencies; clone the repo, run
vagrant up, and start building!
Taking advantage of user-customizations.sh
The idea behind
user-customizations.sh is simple: let users apply their own custom tweaks to the Laravel Homestead VM that won’t impact everyone else on the team.
Homestead already ships with support for
after.sh which, if present, will be run after the main Homestead VM is provisioned;
after.sh is ideal for installing libraries the application depends on, compiling assets, running migrations, etc. This shell script usually gets committed to the Git repository, ensuring that anyone who picks up a copy of the project gets the same tweaks applied.
user-customizations.sh file, on the other hand, is not meant to be committed to a Git repository. Instead, it codifies your personal preferences for the VM. Prefer
nano? Do you have a collection of aliases you can’t live on the command line without? Drop these into your
user-customizations.sh file and (re-)provision Homestead to customize the machine to your liking.
Creating a user-customizations.sh file
after.sh, Laravel Homestead does not ship with a default
user-customizations.sh file: if you want to take advantage of it, simply create one in the root of the project directory (at the same level as the
after.sh) and the Vagrant provisioner will pick it up automatically. You may also use this one-liner, which will also add
user-customizations.sh to your project’s
$ touch user-customizations.sh \
&& grep -q -s -e '^user-customizations.sh$' .gitignore \
|| echo 'user-customizations.sh' >> .gitignore
Another helpful trick would be to create a single
user-customizations.sh somewhere on your machine, then symlink it into new projects: one file can store your preferences across multiple Laravel Homestead instances!
Hopefully this feature will prove useful for teams who love using Laravel Homestead for their apps but tire of making the same customizations on each VM!