How to get Craft CMS 2.5 Running on a Laravel Homestead 3.0.x Vagrant Box

I recently stumbled across Vagrant while setting up Laravel Homestead. Doing PHP development on isolated virtual machines seemed like a good way to keep my Macbook clean while ensuring that my dev environment matched the Linux servers I’d ultimately be deploying to. Also, it’s like all over Hacker News, so it’s gotta be legit.

Laravel Homestead is a nice pre-provisioned Vagrant box that you’re meant to develop Laravel apps on, but I thought: hey, would this also work for Craft CMS? The answer: yes, but not easily.

After burning a couple hours with various error messages before getting something functional running, I figured I’d throw up a quick post to prevent others from wasting their time.

I won’t go into the details on installing Homestead and Craft. You can figure that out from their respective sites. This guide picks up from when you try to run the Craft admin panel for the first time.

The first error you’ll hit: “Mcrypt PHP extension required”

It seems like the version of PHP 7.0 that comes preinstalled on the Homestead box doesn’t have the mcrypt module installed. Craft needs this to run, and will complain: “Mcrypt PHP extension required”.

SSH into your Vagrant box with “vagrant ssh” and run:

sudo apt-get update
sudo apt-get install php7.0-mcrypt

Once this is fixed, you should be able to run the Craft installation process from homestead.app/admin (or wherever your etc/hosts file points to your Homestead box IP).

The second error you’ll hit: “Oops!”

Haha! I said you could run the installation process, not that it would complete successfully! You’ll hit an “Oops!” screen a few seconds into the setup, and it will hang there. Give it 20–30 seconds, then reload the page. It should bring you to the Craft admin panel, even though the setup seemed to have been unsuccessful.

The third and final error: “GROUP BY incompatible with sql_mode=only_full_group_by”

This seems like an issue with the version of SQL that Craft is expecting. Check out the StackExchange answer for details, but in short you need to SSH back into your Vagrant box and run:

echo -e '[mysqld]\nsql-mode=""' | sudo tee --append /etc/mysql/conf.d/craft.cnf > /dev/null
service mysql restart

Craft should run fine after that. Or, I hope it does. I’ve only been running it for a few hours at this point. I’ll update this post if I hit any other showstoppers down the line.