Setting Up Craft CMS 3 Local Development with Laravel Homestead

This article explains how to install Craft 3 on macOS Mojave.

We’re going to use Laravel Homestead for our local development environment.

The advantage of using Homestead is that its tech stack (Ubuntu, PHP, MariaDB, nginx) will match our production environment on Linode. Homestead creates a Linux virtual machine (VM) on your computer (host).

Homestead itself leverages 2 other software packages:

  1. Vagrant
  2. Virtualization software
    either VirtualBox, VMWare, or Parallels

We’re going to use VirtualBox since it’s FREE while VMWare & Parallels need to be licensed.1

PHP 7 & Composer #

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

Additionally, we’re going to install Craft 3 using Composer. If you don’t have Composer installed then follow these installation steps.

Install Vagrant & VirtualBox #

Installing the prerequisites is pretty straightforward since both have installation packages.

  1. Download & install Vagrant
  2. Download & install VirtualBox 5

Install Homestead #

Installing Homestead is a bit more involved since it’s not as easy as downloading an installer.

We’re going to install Homestead using Git. The convention is to clone the repository into a local Homestead folder.

Let’s clone it under a ~/Sites folder.3

cd ~/Sites  
git clone https://github.com/laravel/homestead.git Homestead

Since Homestead is under constant development it’s safer to use a tagged release. This helps ensure you’re working with a stable version. We’ll use v7.19.2.

cd ~/Sites/Homestead
git checkout v7.19.2

Now from inside the Homestead folder run this initialization script.

bash init.sh

Homestead.yaml #

The initialization script creates a Homestead.yaml file inside your Homestead folder.

This file is used to configure the virtual machine. You can specify the database (MySQL or Postgres), the amount of RAM, number of CPU cores to allocate for the VM & define your development sites.

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

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

authorize: ~/.ssh/id_rsa.pub

keys:
    - ~/.ssh/id_rsa

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

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

databases:
    - craft3tut

Let’s run through the options:

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

memory
The amount of RAM you want to allocate from your machine to the VM. The rule of thumb is ⅛ of your machine’s RAM.

My computer has 16GB so I’ve assigned 2GB (2 x 1024 = 2048).

cpus
The number of CPU cores you’ll allocate 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.

provider
Defines the virtualization software. In our case it’s virtualbox.

mariadb: true
We added this line to use MariaDB as our database.

MariaDB is an enhanced, drop-in replacement for MySQL. So you get improved performance but can keep using your favorite MySQL tools.4

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

folders In this section, we define the location for the Craft site; on both your local computer & inside the VM.

folders: map
This is the location of the Craft site on your local machine.

folders: to
This is the location of the Craft site inside the virtual machine machine.

The default folder for Homestead projects within the VM is /home/vagrant/code/.

type: nfs
An interesting tidbit is that your local computer & the VM will sync files across to each other.

So you can edit a file within the VM and it’ll sync back to your Mac. And the more common scenario 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 syncing process can happen a bit more efficiently.

sites
In this section, we define our local development domain & map it the Craft 3 public directory within the VM.

sites: map
Here you define the local development domain.

The convention is to replace the top-level portion of the live domain with .test.5

sites: to
This is the location of the Craft public directory within the VM.

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

databases
Homestead will create an empty database for you. Here you provide the name. We’ve called our database craft3tut.

And that’s all we need to power on the VM. So copy the contents of the Homestead.yaml above into yours & save.

Now make sure you’re in your Homestead folder and power up Homestead.

vagrant up

Go grab a cup of ☕️ cause the installation will take a while.

Configure your local test domain #

In Homestead.yaml, we configured our local domain to demo.crafcmstutorial.test but we actually have to edit our Hosts file to make this work.

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

You’ll be prompted for your macOS admin password to confirm this change. Or you can use a GUI client like Gas Mask.

Install Craft 3 via nystudio107 Scaffold #

So we’re finally ready to install Craft 3. But we’re going to use a scaffold by Andrew Welch of nystudio107.6 It includes the core Craft 3 installation along with additional plugins that help with development & 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 commands because we’ll finish installing via the browser.

Database Config

But first we need to configure the database.

Open .env and update the following lines to use the default Homestead database credentials. Also, make sure the database name matches the one you defined in Homestead.yaml

DB_USER="homestead"
DB_PASSWORD="secret"
DB_DATABASE="craft3tut"

With those in place we can now load our browser.

Go to http://demo.crafcmstutorial.test/admin & you’ll be redirected to the installation page. You’ll know you’re at the right place if you see a psychedelic background with a big red Install Craft button.

Install Craft

  1. Click the button.

  2. ✓ Accept the terms.

  3. Create your admin account.
    Enter your admin user, email & password.

  4. Setup your site info.
    Enter the site name, base URL & language.

  5. Then wait a little bit as Craft finishes installing.

You’ll be redirected to the admin control panel. There isn’t any sample data. Nor even a working front-end. That’s all left up for you to build as you wish.

Welcome to Craft. 🎉

Finish setup of nystudio107 Scaffold #

I lied before. We actually are going to run one of the setup scripts I told you to skip.

I had 2 good reasons to skip the Craft setup script:

  1. Sometimes the Craft CLI has a hard time connecting to the Homestead database.
  2. You would have missed that trippy background screen. 😉

Now that Craft 3 is installed and the database is configured, we can run the nystudio107 setup script.

Go to your project folder
cd ~/Sites/craft3tut

and run ./nys-setup

You’ll see output similar to this:

Welcome to nys-setup

Setting up Craft-Scripts
### scripts/.env.sh 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 .env.sh

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 important change is that site config is now managed in .env.php (instead of the default .env).

Also review config/general.php. Notice how you can control site settings per environment. So devMode & allowUpdates are enabled on local but not on staging or production.

There’s also a section for ALL * environments. I like to set the timezone 'timezone' => 'America/New_York’. And I also prefer to login to the adminCP with username instead of email 'useEmailAsUsername' => false. If you don’t like the default /admin path you can change it to something less obvious ’cpTrigger' => ‘topsecret’,

Frontend Templates

The nystudio107 scaffold does come with some barebones templates but it’s preconfigured to use Tailwind CSS & Vue.js. If you want to continue building upon those starter templates then definitely read this article.

If that’s not within your wheelhouse then update as necessary or redo the install using the standard Craft installation. composer create-project craftcms/craft craft3tut

Conclusion #

So now you have your brand new Craft 3 site running on Laravel Homestead. Go forth and build!

If you’d like to learn how to have your new site load securely (HTTPS) then read this article. When it’s time to update Homestead check out this article.

Now Homestead does have its drawbacks: lots of moving parts (Vargrant, virtual provider & Homestead), somewhat resource heavy, you don’t have full control of the tech stack & finicky configuration which isn’t easy to share across teams.

But for the most part, if you have decent rig & your projects are fairly recent (in terms of tech stack) then identifying any potential server configuration issues early on is worth it for me. Additionally, I can run multiple projects on the same VM.

However, if you need more control of your tech stack (ex: production server is running MariaDB 10.1.37 while most recent Homestead uses 10.3.10) then Homestead may not be a good fit. In that case I’d go with Docker. In a follow-up article, I’ll walkthrough installing Craft 3 locally using Docker.

Agree? Disagree? Let me know @AlexAguilar18 on Twitter.


  1. <p>The performance of VMWare &amp; Parallels tends to be faster than that of VirtualBox. So depending on your development machine, using a commercial option may be worthwhile.&#160;<a href=”#fnref1:1” rev=”footnote” class=”footnote-backref”>&#8617;</a></p>
  2. <p><a href=”https://getgrav.org/blog/macos-sierra-apache-multiple-php-versions”>https://getgrav.org/blog/macos-sierra-apache-multiple-php-versions</a>&#160;<a href=”#fnref1:2” rev=”footnote” class=”footnote-backref”>&#8617;</a></p>
  3. <p>Or use whichever folder you typically use for web projects ex: <code>~/Code</code> or <code>~/Projects</code> &#160;<a href=”#fnref1:3” rev=”footnote” class=”footnote-backref”>&#8617;</a></p>
  4. <p>Like the awesome <a href=”https://www.sequelpro.com/”>Sequel Pro</a>&#160;<a href=”#fnref1:4” rev=”footnote” class=”footnote-backref”>&#8617;</a></p>
  5. <p>Other conventions are <code>.local</code>, <code>.app</code> or <code>.dev</code>. But <code>.test</code> is what Homestead recommends. Additionally, <a href=”https://ma.ttias.be/chrome-force-dev-domains-https-via-preloaded-hsts/”>Google actually owns <code>.dev</code></a> which has stopped working as expected in recent versions of Chrome.&#160;<a href=”#fnref1:5” rev=”footnote” class=”footnote-backref”>&#8617;</a></p>
  6. <p><a href=”https://github.com/nystudio107/craft”>https://github.com/nystudio107/craft</a>&#160;<a href=”#fnref1:6” rev=”footnote” class=”footnote-backref”>&#8617;</a></p>

Alex Aguilar, Partner, Software Engineer

Alex Aguilar

Partner, Software Engineer