Explaining Laravel Settler

If you view the readme.md of the Laravel Settler repository you’ll likely notice the not so inviting “You probably don’t want this repo”. While I try to be as inviting as I can across all open source repositories this one has always been a bit of the exception. The reason for this is because Settler has no continuous integration or continuous deployment (CI/CD) pipeline. There’s no easy way for us to know which changes will cause issues or not. Over the years I’ve come to learn what to look out for, but for those who want to contribute, they may be put off by all of this.

Let’s clarify a few things which are often a source of confusion around Homestead & Settler.

Settler is the base box

The Settler repository is what we use to build the base box of Homestead. A Vagrant base box is a snapshot of a virtual machine. A fancy zip file for all intents and purposes. When you add a Vagrant box to your system it is downloaded and extracted to ~/.vagrant.d/boxes. If you look at my machine we can see I have 2 boxes: Svpernova09/AmazonLinux-2 and laravel/homestead:

$ ll
drwxr-xr-x  4 halo  staff  128 Jun  5 20:21 Svpernova09-VAGRANTSLASH-AmazonLinux-2/
drwxr-xr-x  5 halo  staff  160 Jun  5 17:13 laravel-VAGRANTSLASH-homestead/

When you run vagrant up to spin up a new instance of a Vagrant machine Vagrant will copy the box from this location into .vagrant in the same folder which you ran vagrant up from. This is how Vagrant accomplishes the disposable virtual machine aspect of being able to blow away / destroy a Vagrant machine without having to download the base box/image again. Vagrant is a really fancy wrapper around managing versioned virtual machine snapshots.

We should have named the base box “Settler”

You can find all of the released base box information on Vagrant Cloud. The entire confusion of Homestead “the repo” versus Homestead “the base box” stems from the fact we named this Homestead as well. This is why you’ll always see me referring to Homestead the application as “the repo” and Settler as “the base box”.

Each Vagrant Cloud version relates to a tagged release of Laravel Settler (The only exception here is alpha/beta versions). You can see a few alpha versions but if you find version v7.2.1 you’ll see it has a link to the Settler Release which contains the changes since the previous release. This is where I document the release notes for each version.

You should always use the latest release of Homestead & Settler

You should always keep Homestead (and Settler!) up to date. Since the virtual machine is just a snapshot in time of a Ubuntu Linux server it will eventually get out of date and things may break. Specifically, something we’ve had to deal with a lot recently is PPA archives updating or changing GPG keys which require a command to run to update them. This has really highlighted some shortcomings in how we develop optional features. This has to lead to us fixing those issues as we run into them and ultimately makes our feature installer scripts much more robust.

You the Homestead user should never run apt-get upgrade. You certainly can if you want to, I’m not the police after all. We try to push out a base box update at least once a quarter and sometimes as often as monthly. If you’re keeping the base box up to date you shouldn’t have to worry about installing package updates. If you’re chasing some weird bug, feel free to upgrade since you can always roll back whenever you need to by destroying the virtual machine.

Settler is a bash script

If you’ve ever written a bash script, you can read the guts of settler. The scripts/provision.sh shell script is where ALL the magic happens. provision.sh is what turns an ordinary Ubuntu 18.04 virtual machine into “Homestead”. The bash script gets added to another repository which is not managed by Laravel. Homestead is built on top of chef/bento which is a repository maintained by the fine folks at Chef which contain dozens of Packer templates for building virtual machines. Packer.io is another product by the makers of Vagrant, Hashicorp. Packer is an application that transforms JSON files into virtual machines. Like Vagrant, Packer will use providers to perform the virtualization. The Bento repository is a collection of managed templates for building many different operating systems (including Windows!).

I hope this provides some insight into the world of Homestead. In our next installment, we’ll cover how to build the base box from the Settler repository.

Happy Coding.