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:
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.
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
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
git checkout v7.19.2
Now from inside the Homestead folder run this initialization script.
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:
The ip address used by the VM. Don’t change this value.
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).
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.
Defines the virtualization software. In our case it’s virtualbox.
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
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.
This is the location of the Craft site on your local machine.
This is the location of the Craft site inside the virtual machine machine.
The default folder for Homestead projects within the VM is
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.
In this section, we define our local development domain & map it the Craft 3 public directory within the VM.
Here you define the local development domain.
The convention is to replace the top-level portion of the live domain with
This is the location of the Craft public directory within the VM.
In Craft 3, the web root is the
Homestead will create an empty database for you. Here you provide the name. We’ve called our database
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.
Go grab a cup of ☕️ cause the installation will take a while.
Configure your local
test domain #
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:
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.
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.
But first we need to configure the database.
.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
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.
- Click the button.
- ✓ Accept the terms.
- Create your admin account.
Enter your admin user, email & password.
- Setup your site info.
Enter the site name, base URL & language.
- 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:
- Sometimes the Craft CLI has a hard time connecting to the Homestead database.
- You would have missed that trippy background screen. 😉
Now that Craft 3 is installed and the database is configured, we can run the nystudio107
Go to your project folder
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
config/general.php. Notice how you can control site settings per environment. So
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’,
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
So now you have your brand new Craft 3 site running on Laravel Homestead. Go forth and build!
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.
The performance of VMWare & Parallels tends to be faster than that of VirtualBox. So depending on your development machine, using a commercial option may be worthwhile. ↩
Or use whichever folder you typically use for web projects ex:
Other conventions are
.testis what Homestead recommends. Additionally, Google actually owns
.devwhich has stopped working as expected in recent versions of Chrome. ↩