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:

https://twitter.com/HomesteadDev/status/1036988846183985152

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.

The 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 vim over 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

Unlike 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 Vagrantfile and 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 .gitignore file:

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!