A quick and easy local environment for Craft 3

Like many developers, we work on web projects locally before deploying them to our staging and production servers. Since we’re not sysadmins, we’ve struggled to find the right environment for running Craft locally with a minimum of headaches. We’ve tried MAMP, Homestead, Valet, Docker, and others, and come up against roadblocks with them all. Here I’ll discuss how we use a free app called Local (from WordPress host Flywheel) to install Craft 3 quickly with a minimum of fuss.

Local is a nice GUI for Docker with Debian, PHP 7.1, Apache, nginx, and MySQL preinstalled. It’s easy to manage multiple sites and does the work of configuring your local host file, setting up a mailcatcher, installing security certificates, and syncing your site with your local filesystem. In other words, it does everything you would do if you were setting up a virtual environment from scratch, with much less work.

Sound good? Get started by downloading Local from the Flywheel website. I use a Mac but there is a Windows version available as well. Install Local and you’ll start with a blank application like this:

Go ahead and click the “Create A New Site” button to get started. Give the new site a name and choose a URL. You can change the default site path if you would like to change where the files are stored in your local filesystem.

Next, choose your environment. We prefer a custom environment with PHP 7.1.x, nginx, and MySQL 5.6 since that most closely mirrors our production environment. Local will download the necessary files the first time you choose this configuration, so go get a cup of coffee.

Next Local will ask about your WordPress installation. Huh? Since Local (and Flywheel) are WordPress-oriented, you have to fill out some very basic WP information. We’ll be deleting the WordPress installation anyway so just use dummy data here.

¯\_(ツ)_/¯

Once everything has been installed, you’ll be back at the Local homescreen.

Now it’s time to install Craft in just a few steps:

  1. Install Composer
  2. Use Composer to install the Craft 3 beta
  3. Update Local’s web folder to point to Craft’s public folder
  4. Update Craft to use Local’s database

Easy.

First, let’s install Composer. Right-click on the name of the site and choose “Open Site SSH” from the contextual menu.

Hey, there are some other cool options in there too.

From the terminal window, type the following two commands to install Composer:

apt-get update && apt-get install -y curl
curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin — filename=composer
Nice.

Now that we’ve installed Composer, it’s time to install Craft. Straight from the documentation:

composer create-project craftcms/craft PATH -s beta

In this case, the PATH is /app/craft, so the terminal command (in the same SSH window) should look like this:

composer create-project craftcms/craft /app/craft -s beta 

You’re going to see a warning here about not running Composer as root, but that’s OK. Root is the only user in this VM, so we don’t have a choice. Since this is a virtual machine and not a public website, the security implications are minimal. Don’t do this in a public environment or on any kind of production site. When Craft is done with installation, you’ll see something like this:

Boom

Here’s where I came across my only hiccup: the command line setup script wouldn’t run. This might have something to do with the local environment, running Composer as root, or even a problem with the Craft beta. In any case, it’s easy to finish the setup with a text editor, so it’s not really a problem.

Next it’s time to change the web root folder. Local uses a directory called “public” to store it’s files. You can delete that directory, since we’ll be using Craft’s “web” directory instead.

To do that, we need to modify the nginx site.conf file. Local’s configuration files are in a folder called “conf”, which is a sibling to the “app” directory. Open conf/nginx/site.conf in your favorite text editor and change the server root from /app/public/ to app/craft/web/

The last thing we need to do (I promise) is the add Local’s database configuration to Craft’s .env file (located in the /app/craft/ directory). Since the filename starts with a dot, it may not be visible in your Finder. Use your favorite command line tool to edit this file, or use a directory browser such as Forklift or Transmit to display hidden files.

The relevant details for the .env file are:

# The database username to connect with
CRAFT_DB_USER=”root”
# The database password to connect with
CRAFT_DB_PASSWORD=”root”
# The name of the database to select
CRAFT_DB_DATABASE=”local”

Remember, this is a local environment. Please don’t ever use the root user on a public site.

Almost there! Now from the Local app, restart your site by right clicking the site name and choose “Restart” from the contextual menu.

You should now be able to finish the setup from your browser. The installation URL for our site is http://craft-3.dev/admin/install.

Et voilà!

Now I’ve got some good news for you: Local has a blueprint feature that lets you to use this install as a starting point for new projects. I like to add a few favorite plugins, a base template, and set up my asset pipeline, and then clone this site whenever I start a new project.

Questions? Comments? Pizza 🍕? I’m @dalton in the Craft Slack, feel free to get in touch. And you can see some of our work at https://madebyraygun.com/.