Setting up Statamic v3 on MacOS Part 1 of 4 – Composer + Valet

January 7th 2021 by Jay George

In this series, we'll get Statamic set up locally along with a publishing workflow. Statamic is a brilliant content management system once you're up and running, but setting up a developer environment can be quite daunting—especially if you're not used to dealing with developer environments.

There are a growing number of official videos detailing how to get started, which you can find here. I made these videos to document a few gotchas, and since I had recently clean-installed macOS Big Sur, there are fewer variables, and I should run into similar problems that you do.

Do You Need to Do It This Way?

I'll be using a specific setup with Statamic, but you can indeed use something more basic. If you're used to running your local environment through MAMP, you can get Statamic running through that too.

BUT—I've nagged the Statamic community for the last 6 months, and the set-up I'll show you is either the easiest way to run Statamic or the most recommended. So if you'd like to make your life easier in the long-run, then follow me.

Using Laravel’s Valet as a Minimalist Developer Environment

Valet is in some ways comparable to MAMP—which is one of the most popular GUIs (Graphical User Interface) for running a development environment locally on macOS.

What we are getting with Valet is NGINX (a webserver), and PHP (a programming language). These two things are needed to run Statamic, but they're also handy for HTML prototyping, which means Valet is still really handy to keep around.

What If You Already Have MAMP Installed?

MAMP and Valet can conflict if they're running at the same time. I believe this is due to them both trying to write domains to host files simultaneously. I've written some basic instructions here on how to deal with this. Basically, you need to make sure they're not running at the same time.

Installing Valet Step 1 – Installing Homebrew

Homebrew is a package manager for macOS. Let's install it.

Go to https://brew.sh/
Click the little clipboard button next to the command to copy it to your clipboard.
Open the Terminal application. Paste in the command you've just copied.
Press “return” when prompted to go ahead and install Homebrew

Homebrew will take a bit of time to install if you haven't already got Xcode installed (Xcode is a macOS application made by Apple that's used by software developers).

Installing Valet Step 2 – Installing Composer

Composer is similar to a package manager but more specifically it's used to manage ‘dependencies’. We'll need it to install Valet, and conveniently we'll also need it to install Statamic.

Download Composer here – https://getcomposer.org/download
Similar to Homebrew, copy the command and paste it into Terminal, then hit enter.
You may need to log out and back in again at this point.

To use Composer globally you need to move it. Run this command:

sudo mv composer.phar /usr/local/bin/composer

Installing Valet Step 3 – Installing Valet with Composer

Now that Composer is installed we can use it to install Valet. Run this command to add Valet as a dependency:

composer global require laravel/valet

Once it's added as a dependency we can install it with this command:

valet install

At this point, if you get a “command not found” error, run this command:

test -d ~/.composer && bash ~/.composer/vendor/bin/valet install || bash ~/.config/composer/vendor/bin/valet install

Once this command has finished running you should see a “Valet installed successfully!” message.

Testing That Valet is Working OK

Make sure you have a “Sites” folder in your home directory.
Create a subfolder within “Sites” and call it whatever your domain will be. For example, if I want to run “jaygeorge.co.uk” then I would name my subfolder “jaygeorge”
Add a new file in the subfolder and call it “index.php”

In index.php try to ‘echo’ out some text by adding the following command:

<?php echo 'hello world'; ?>

Go back to Finder and use “cmd + c” while highlighting the subfolder (in my case jaygeorge).
Type “cd ” in Terminal then use “cmd + v” in Terminal to paste in your path. This will make sure that Terminal is in the right directory

Now use the command:

valet link

This will effectively create a domain name for that folder. You can now type:

valet links

This will show you the new link you created.

Copy the link that Valet has just created e.g. “http://jaygeorge.co.uk” and test it out. You should see “hello world” in your browser, which confirms that Valet has created the domain, and PHP is running.

Getting Valet Running Over SSL

In Terminal run the command:

valet secure yourdomainnamehere

For example, “valet secure jaygeorge”. Valet should restart its webserver and issue a domain certificate.

If you refresh your domain you should be redirected to https://yourdomainname

Changing Valet’s TLD

By default Valet will run everything domain as domainname.test. If you're fine with that then feel free to skip this step. I personally like ‘.wip’ – it makes the site feel less like a laboratory and more like a project.

At this point, it's useful to bear in mind that “.local” my have some issues since it's traditionally reserved for Apple's Bonjour protocol. It's also useful to think about how Statamic decides whether you are running your site locally or not.

Changing Valet's TLD to wip is as simple as running:

valet domain wip