Setting up a local dev environment for Craft CMS with Laravel Homestead

4 min readDec 12, 2014

Who is this for?

If the title didn’t give it away — Anyone who wants to set up a local development environment using Laravel Homestead 2.0 to develop Craft CMS sites.

This is simply a mashup of the official docs for both products at the time that I am writing this. I recommend that you follow their documentation and use this to get a feel for the overall setup process.

An alternative to MAMP

Like many, I have been using MAMP for some time to set up a local development environment on my Mac. It seemed like I was forever running into problems with MAMP — from MySQL not starting to Apache errors. When I updated to Yosemite and MAMP completely fell over, I knew it was time to look seriously at alternatives.

I stumbled across this video from the guys over at Straight up Craft discussing setting up Craft with Vagrant. Jason McCallister discusses several options for setting up vagrant. In particular, he lists Laravel Homestead as his preferred option. Homestead is basically a preconfigured Vagrant box that happens to work great out the box for developing Craft sites.

Homestead 2.0 has only just been released as of me writing this (December 2014). I ran into some confusion following tutorials around the web as the setup process for 2.0 is a bit different.

Setting up your first Craft site with Homestead

Installing VirtualBox & Vagrant

Before launching your Homestead environment, you must install [VirtualBox](https://www.virtualbox.org/) and [Vagrant](https://www.vagrantup.com/). Both of these software packages provide easy-to-use visual installers for all popular operating systems.

Adding the Vagrant Box

Once VirtualBox and Vagrant have been installed, you should add the laravel/homestead box to your Vagrant installation using the following command in your terminal. It will take a few minutes to download the box, depending on your Internet connection speed:

vagrant box add laravel/homestead

Install Composer

In order to install homestead in the next section of this tutorial, you must first install composer, a PHP dependency manger. Follow the steps here to download and install composer.

Installing Homestead

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/bin directory in your PATH so the homestead executable is found when you run the homestead command in your terminal.

I ran into problems with this part of Homestead’s documentation and was able to resolve this by adding the following to my .profile or .bashrc file.

export PATH=$PATH:$HOME/bin
 PATH=$PATH:~/.composer/vendor/bin
 export PATH

Once you have installed the Homestead CLI tool, run the init command to create the Homestead.yaml configuration file:

homestead init

The Homestead.yaml file will be placed in the ~/.homestead directory. If you’re using a Mac or Linux system.

Download Craft CMS

Next you need to download craft cms.

I’ve added a folder to my home directory called “sites” and put the contents of the craft.zip file in a folder called “my-craft-site” within the sites folder.

Users/mattcollins/sites/my-craft-site/

Configure Homestead for your Craft

Open the homestead.yaml file the terminal or text editor. You’ll find it here

~/.homestead/Homestead.yaml

The file comes with a set of default configurations. We need to make the following changes:

Set your SSH key

Don’t have an SSH key? You can create an SSH key pair using the following command:

ssh-keygen -t rsa -C “your_email@example.com”

Once you have created a SSH key, specify the key’s path in the authorize property of your Homestead.yaml file.

authorize: /Users/mattcollins/.ssh/id_rsa.pubkeys:
 — /Users/mattcollins/.ssh/id_rsa

Add a folder for your Craft site

folders:
 — map: /Users/mattcollins/sites/my-craft-site
 to: /home/vagrant/sites/my-craft-site

Configure your Craft

To add our craft site, we need to map a domain to the location of craft’s index.php file.

sites:
 — map: my-craft-site.dev
 to: /home/vagrant/sites/my-craft-site/public

Add a database for your Craft site

databases:
 — my-craft-site

Save the homestead.yaml file.

Tell Craft how to connect to your homestead database

Open up your craft/config/db.php file on your server. This file holds some settings that tell Craft how it can connect to your database.

Set ‘database’ to the database set in homestead.yaml: ‘my-craft-site’
Set ‘user’ to homestead’s default user: ‘homestead’
Set ‘password’ to homestead’s default passoword: ‘secret’

Add a domain to the host file on your machine

The hosts file will redirect your requests for our craft domain into your Homestead environment. This file is located at /etc/hosts. The lines you add to this file will look like the following:

192.168.10.10 my-craft-site.dev

Launch The Vagrant Box

Now that we have set everything up we need to run the ‘homestead up’ command in your terminal. Vagrant will boot the virtual machine, and configure our site automatically!

Launch the Craft Installer

Now that our virtual machine is running, we need to run the craft installer. Point your browser to http://my-craft-site.dev/admin. If you see a monkey in your browser, you’ve done everything right!

That’s all folks

Whilst there is a little bit of upfront setup, I’ve found working with Homestead to be a breath of fresh air coming from MAMP. I suggest reading further on Homestead’s documentation about launching and destroying vagrant boxes and the workflow for adding additional sites.