Building the Homestead Box

This guide provides the complete instructions for building a Homestead Vagrant box from the Laravel Settler source scripts. This process is for developers who want to create a custom version of the Homestead box.

Prerequisites

Before you begin, you must have the following software installed on your local machine:

  1. Packer: A tool for creating identical machine images for multiple platforms from a single source configuration.
  2. Git: For cloning the required repositories.
  3. A virtualization provider compatible with Packer and Bento, such as VirtualBox, VMware, or Parallels.

Step-by-Step Build Process

The build process involves cloning both Laravel Settler and its base, Chef's Bento, and then linking them together before running Packer.

1. Clone Repositories

Clone the laravel/settler and chef/bento repositories into the same parent directory. It is crucial that they are siblings in the file system.

git clone https://github.com/laravel/settler.git
git clone https://github.com/chef/bento.git

Your directory structure should look like this:

my-projects/
├── bento/
└── settler/

Settler includes helper scripts to automatically link its provisioning files into the Bento Packer templates. Navigate into the settler directory and run the appropriate script for your operating system.

For macOS / Linux:

cd settler
./bin/link-to-bento.sh

This script will:

  • Create symbolic links from the Settler provisioning scripts (scripts/amd64.sh, scripts/arm.sh) into the Bento scripts directory.
  • Modify Bento's Packer configuration (pkr-builder.pkr.hcl) to use the Settler script instead of the default cleanup script.
  • Update the Packer variables (pkr-variables.pkr.hcl) to increase the virtual disk size.

For Windows (using PowerShell):

You may first need to adjust your PowerShell execution policy to allow local scripts to run.

# Run this command in an administrative PowerShell terminal
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then, run the linking script:

cd settler
./bin/link-to-bento.ps1

3. Run Packer Build

After linking the repositories, all subsequent actions take place inside the bento directory. Navigate to it:

cd ../bento

From here, you will use the standard Packer build process as defined by the Bento project. The link-to-bento.sh script has already configured the pkr-builder.pkr.hcl file for you.

To build the box (for example, an Ubuntu 22.04 box for VirtualBox), you would run a command similar to this. Note that you may need to specify your desired builder (e.g., virtualbox-iso.vm).

# Example for building Ubuntu 22.04 with VirtualBox
# The exact command may vary based on Bento's current configuration
packer build -only='virtualbox-iso.vm' packer_templates

Packer will now begin the build process. It will download the Ubuntu ISO, boot a new virtual machine, run the automated installation using the preseed.cfg from Settler, execute the main homestead_amd64.sh provisioning script, and finally package the result into a .box file ready for use with Vagrant.