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.¹

PHP 7 & Composer #

Craft 3 requires PHP 7. So you need to have PHP 7 installed on your local machine.²

We’re also going to install Craft 3 using Composer. If you don’t have it 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

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.³

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/craft3demo
      to: /home/vagrant/code/craft3demo     
      type: nfs  


sites:
    - map: craft3demo.test
      to: /home/vagrant/code/craft3demo/web   

databases:
    - craft3demo

Let’s run through the options:

ip
The ip address used by the VM. The default value is fine.

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.⁴

authorize and keys
The default values are fine.

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
Your local computer and the VM will sync files across to each other. So when you edit a file on your Mac it’ll be synced to the VM.

By enabling the NFS option, the 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.⁵

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 craft3demo.

And that wraps up the tour of Homesead.yaml, copy the contents from the example above into yours & save.

Make sure you’re in your Homestead folder and start it.

cd ~/Sites/Homestead   
vagrant up

Now go grab a cup of ☕️ because the installation will take a while.

Configure local .test domain #

In Homestead.yaml, we configured our local domain to craft3demo.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 craft3demo.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.⁶ 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 craft3demo

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="craft3demo"

With those in place we can now load our browser.

Go to http://craft3demo.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.

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/craft3demo

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 craft3demo

Conclusion #

You now have a brand new Craft 3 site running on Laravel Homestead. Go forth & build something awesome!

Homestead does have its drawbacks:

• lots of moving parts (Vagrant, virtual provider & Homestead)
• fairly resource heavy
• you don’t have full control of the tech stack
• finicky configuration which isn’t easy to share with teammates

But if you have robust workstation & your project runs on a recent tech stack, then catching potential server issues early (aka before deploying to production) is a fair tradeoff. Also, I can run multiple projects on the same VM. And each project with custom local domains.

If you need more fine-tuned control of your tech stack (ex: specific database version) then Homestead may not be a good fit. In that case I’d go with Docker. In a follow-up article, I walkthrough how to install Craft 3 locally using Lando Docker.