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 you need to have PHP 7 installed on your local machine.2
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.
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
cd ~/Sites/Homestead 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/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:
The ip address used by the VM. The default value is fine.
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
authorize and keys
The default values are fine.
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 /home/vagrant/code/.
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.
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 .test.5
This is the location of the Craft public directory within the VM.
In Craft 3, the web root is the web folder.
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:
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 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.
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.
- 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 craft3demo
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.
The performance of VMWare & Parallels tends to be faster than that of VirtualBox. So depending on your local development machine, using a commercial option might be worthwhile. ↩
Or the folder you typically use for your projects ex: ~/Code or ~/Projects ↩
Other conventions are .local, .app or .dev. But .test is what Homestead recommends. Additionally, Google actually owns .dev which has stopped working as expected locally in recent versions of Chrome & Firefox.↩