Setting Up Craft CMS 3 Local Development with Laravel Homestead

This arti­cle explains how to install Craft 3 on macOS Mojave.

We’re going to use Lar­avel Home­stead for our local devel­op­ment environment. 

The advan­tage of using Home­stead is that its tech stack (Ubun­tu, PHP, Mari­aDB, nginx) will match our pro­duc­tion envi­ron­ment on Lin­ode. Home­stead cre­ates a Lin­ux vir­tu­al machine (VM) on your com­put­er (host).

Home­stead itself lever­ages 2 oth­er soft­ware packages: 

  1. Vagrant
  2. Vir­tu­al­iza­tion software
    either Vir­tu­al­Box, VMWare, or Par­al­lels

We’re going to use Vir­tu­al­Box since it’s FREE while VMWare & Par­al­lels need to be licensed.1

PHP 7 & Com­pos­er #

Craft 3 requires PHP 7. So it’ll be eas­i­er to install if you already have PHP 7.0+ installed on your local machine.2

Addi­tion­al­ly, we’re going to install Craft 3 using Com­pos­er. If you don’t have Com­pos­er installed then fol­low these instal­la­tion steps.

Install Vagrant & Vir­tu­al­Box #

Installing the pre­req­ui­sites is pret­ty straight­for­ward since both have instal­la­tion packages.

  1. Down­load & install Vagrant
  2. Down­load & install Vir­tu­al­Box 5

Install Home­stead #

Installing Home­stead is a bit more involved since it’s not as easy as down­load­ing an installer.

We’re going to install Home­stead using Git. The con­ven­tion is to clone the repos­i­to­ry into a local Home­stead folder. 

Let’s clone it under a ~/Sites fold­er.3

cd ~/Sites  
git clone Homestead

Since Home­stead is under con­stant devel­op­ment it’s safer to use a tagged release. This helps ensure you’re work­ing with a sta­ble ver­sion. We’ll use v7.19.2.

cd ~/Sites/Homestead
git checkout v7.19.2

Now from inside the Home­stead fold­er run this ini­tial­iza­tion script. 


Homestead.yaml #

The ini­tial­iza­tion script cre­ates a Homestead.yaml file inside your Home­stead folder. 

This file is used to con­fig­ure the vir­tu­al machine. You can spec­i­fy the data­base (MySQL or Post­gres), the amount of RAM, num­ber of CPU cores to allo­cate for the VM & define your devel­op­ment sites.

Below is the Homestead.yaml file we’ll use for this tutorial.

ip: ""
memory: 2048
cpus: 2
provider: virtualbox
mariadb: true

authorize: ~/.ssh/

    - ~/.ssh/id_rsa

    - map: ~/Sites/craft3tut
      to: /home/vagrant/code/craft3tut     
      type: nfs  

    - map: demo.crafcmstutorial.test
      to: /home/vagrant/code/craft3tut/web   

    - craft3tut

Let’s run through the options:

The ip address used by the VM. Don’t change this value.

The amount of RAM you want to allo­cate from your machine to the VM. The rule of thumb is ⅛ of your machine’s RAM

My com­put­er has 16GB so I’ve assigned 2GB (210242048).

The num­ber of CPU cores you’ll allo­cate to the VM. I have a quad-core machine so I’ve assigned 2 cores to the VM

If you have a dual-core machine then only assign 1.

Defines the vir­tu­al­iza­tion soft­ware. In our case it’s vir­tu­al­box.

mariadb: true
We added this line to use Mari­aDB as our database. 

Mari­aDB is an enhanced, drop-in replace­ment for MySQL. So you get improved per­for­mance but can keep using your favorite MySQL tools.4

authorize and keys
You don’t need to change these values.

folders In this sec­tion, we define the loca­tion for the Craft site; on both your local com­put­er & inside the VM.

folders: map
This is the loca­tion of the Craft site on your local machine. 

folders: to
This is the loca­tion of the Craft site inside the vir­tu­al machine machine. 

The default fold­er for Home­stead projects with­in the VM is /home/vagrant/code/.

type: nfs
An inter­est­ing tid­bit is that your local com­put­er & the VM will sync files across to each other. 

So you can edit a file with­in the VM and it’ll sync back to your Mac. And the more com­mon sce­nario is also true, when you edit a file on your Mac it’ll be synced to the VM.

By enabling the NTFS option, that file sync­ing process can hap­pen a bit more efficiently. 

In this sec­tion, we define our local devel­op­ment domain & map it the Craft 3 pub­lic direc­to­ry with­in the VM

sites: map
Here you define the local devel­op­ment domain. 

The con­ven­tion is to replace the top-lev­el por­tion of the live domain with .test.5

sites: to
This is the loca­tion of the Craft pub­lic direc­to­ry with­in the VM

In Craft 3, the web root is the web folder.

Home­stead will cre­ate an emp­ty data­base for you. Here you pro­vide the name. We’ve called our data­base craft3tut.

And that’s all we need to pow­er on the VM. So copy the con­tents of the Homestead.yaml above into yours & save.

Now make sure you’re in your Home­stead fold­er and pow­er up Homestead.

vagrant up

Go grab a cup of ☕️ cause the instal­la­tion will take a while.

Con­fig­ure your local test domain #

In Homestead.yaml, we con­fig­ured our local domain to demo.crafcmstutorial.test but we actu­al­ly have to edit our Hosts file to make this work.

On Mac, you’ll edit this file /etc/hosts by adding: demo.crafcmstutorial.test

You’ll be prompt­ed for your macOS admin pass­word to con­firm this change. Or you can use a GUI client like Gas Mask.

Install Craft 3 via nystudio107 Scaf­fold #

So we’re final­ly ready to install Craft 3. But we’re going to use a scaf­fold by Andrew Welch of nystudio107.6 It includes the core Craft 3 instal­la­tion along with addi­tion­al plu­g­ins that help with devel­op­ment & maintenance. 

Go to your projects folder.
cd ~/Sites/

and install the scaffold
composer create-project nystudio107/craft craft3tut

Once it’s done — SKIP the steps where it says to run the final setup com­mands because we’ll fin­ish installing via the browser. 

Data­base Config

But first we need to con­fig­ure the database. 

Open .env and update the fol­low­ing lines to use the default Home­stead data­base cre­den­tials. Also, make sure the data­base name match­es the one you defined in Homestead.yaml


With those in place we can now load our browser.

Go to http://demo.crafcmstutorial.test/admin & you’ll be redi­rect­ed to the instal­la­tion page. You’ll know you’re at the right place if you see a psy­che­del­ic back­ground with a big red Install Craft button. 

Install Craft

  1. Click the button. 
  2. ✓ Accept the terms.
  3. Cre­ate your admin account.
    Enter your admin user, email & password.
  4. Set­up your site info.
    Enter the site name, base URL & language.
  5. Then wait a lit­tle bit as Craft fin­ish­es installing.

You’ll be redi­rect­ed to the admin con­trol pan­el. There isn’t any sam­ple data. Nor even a work­ing front-end. That’s all left up for you to build as you wish. 

Wel­come to Craft. 🎉

Fin­ish set­up of nystudio107 Scaf­fold #

I lied before. We actu­al­ly are going to run one of the setup scripts I told you to skip. 

I had 2 good rea­sons to skip the Craft set­up script: 

  1. Some­times the Craft CLI has a hard time con­nect­ing to the Home­stead database. 
  2. You would have missed that trip­py back­ground screen. 😉

Now that Craft 3 is installed and the data­base is con­fig­ured, we can run the nystudio107 setup script. 

Go to your project folder
cd ~/Sites/craft3tut

and run ./nys-setup

You’ll see out­put sim­i­lar to this:

Welcome to nys-setup

Setting up Craft-Scripts
### scripts/ file already exists, exiting...

Setting up Craft 3 Multi-Environment
- copied vendor/nystudio107/craft3-multi-environment/config/db.php to config/db.php
- copied vendor/nystudio107/craft3-multi-environment/config/general.php to config/general.php
- copied vendor/nystudio107/craft3-multi-environment/config/volumes.php to config/volumes.php
- copied vendor/nystudio107/craft3-multi-environment/web/index.php to web/index.php
- copied vendor/nystudio107/craft3-multi-environment/craft to craft
- copied vendor/nystudio107/craft3-multi-environment/example.env.php to .env.php
- setting up .env.php

You will still need to set up your REMOTE_ settings in

Installing plugins
- installing plugin async-queue
- installing plugin eager-beaver
- installing plugin image-optimize
- installing plugin minify
- installing plugin routemap
- installing plugin typogrify

Installing NodeJS packages via yarn (this may take a while)
sh: yarn: command not found

Setup complete. Have a nice day!

The most impor­tant change is that site con­fig is now man­aged in .env.php (instead of the default .env).

Also review config/general.php. Notice how you can con­trol site set­tings per envi­ron­ment. So devMode & allowUpdates are enabled on local but not on stag­ing or pro­duc­tion.

There’s also a sec­tion for ALL * envi­ron­ments. I like to set the time­zone 'timezone' => 'America/New_York’. And I also pre­fer to login to the adminCP with user­name instead of email 'useEmailAsUsername' => false. If you don’t like the default /admin path you can change it to some­thing less obvi­ous ’cpTrigger' => ‘topsecret’,

Fron­tend Templates

The nystudio107 scaf­fold does come with some bare­bones tem­plates but it’s pre­con­fig­ured to use Tail­wind CSS & Vue.js. If you want to con­tin­ue build­ing upon those starter tem­plates then def­i­nite­ly read this article. 

If that’s not with­in your wheel­house then update as nec­es­sary or redo the install using the stan­dard Craft instal­la­tion. composer create-project craftcms/craft craft3tut

Con­clu­sion #

So now you have your brand new Craft 3 site run­ning on Lar­avel Home­stead. Go forth and build!

If you’d like to learn how to have your new site load secure­ly (HTTPS) then read this arti­cle. When it’s time to update Home­stead check out this article.

Now Home­stead does have its draw­backs: lots of mov­ing parts (Var­grant, vir­tu­al provider & Home­stead), some­what resource heavy, you don’t have full con­trol of the tech stack & finicky con­fig­u­ra­tion which isn’t easy to share across teams. 

But for the most part, if you have decent rig & your projects are fair­ly recent (in terms of tech stack) then iden­ti­fy­ing any poten­tial serv­er con­fig­u­ra­tion issues ear­ly on is worth it for me. Addi­tion­al­ly, I can run mul­ti­ple projects on the same VM.

How­ev­er, if you need more con­trol of your tech stack (ex: pro­duc­tion serv­er is run­ning Mari­aDB 10.1.37 while most recent Home­stead uses 10.3.10) then Home­stead may not be a good fit. In that case I’d go with Dock­er. In a fol­low-up arti­cle, I’ll walk­through installing Craft 3 local­ly using Docker.

Agree? Dis­agree? Let me know @AlexAguilar18 on Twitter.

  1. The per­for­mance of VMWare & Par­al­lels tends to be faster than that of Vir­tu­al­Box. So depend­ing on your devel­op­ment machine, using a com­mer­cial option may be worth­while. 

  2. https://​get​grav​.org/​b​l​o​g​/​m​a​c​o​s​-​s​i​e​r​r​a​-​a​p​a​c​h​e​-​m​u​l​t​i​p​l​e​-​p​h​p​-​v​e​r​sions 

  3. Or use whichev­er fold­er you typ­i­cal­ly use for web projects ex: ~/Code or ~/Projects 

  4. Like the awe­some Sequel Pro 

  5. Oth­er con­ven­tions are .local, .app or .dev. But .test is what Home­stead rec­om­mends. Addi­tion­al­ly, Google actu­al­ly owns .dev which has stopped work­ing as expect­ed in recent ver­sions of Chrome. 

  6. https://​github​.com/​n​y​s​t​u​d​i​o​107​/​craft 

Alex Aguilar, Partner, Software Engineer

Alex Aguilar

Partner, Software Engineer