The easiest way to install Magento 2 on macOS using Valet+
Setting up Magento 2 locally can be pretty painful for several different reasons; however, it doesn't have to be. There's a great tool called Valet+ from the guys over at WeProvide that enables anyone developing on macOS to quickly set up a blazing fast local development environment for Magento 2. It also allows you to easily set up and host other software in a similarly straightforward fashion.
A number of us internally here at Magento are using this exact setup for our day to day development. Working with this setup is incredibly quick and easy.
I've created this easy to follow tutorial from a brand new fresh installation of macOS, and if you already have other software on your computer, you may wish to uninstall conflicting versions before continuing. If you do run into any issues, please do leave a comment and I'll try my best to help. Let's get on with setting up, in my opinion, the best Magento 2 local development experience on macOS.
Existing Apache
You may not know this but your Mac ships with a built in version of Apache. Annoyingly it's most likely running on port 80 which Valet+ requires to function. We can turn off Apache and disable it from starting at boot with the following command:
sudo /usr/sbin/apachectl stop
sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist
Once that's done we're ready for an exciting journey of getting the fastest Magento 2 installation you could dream of!
Homebrew
As with any easy installation, we require a good, robust package manager to do the majority of the hard work for us. In this case, we'll use the world famous Homebrew.
Installation is simple; firstly we need to open Terminal which can be easily found by opening Spotlight via the top right search icon, entering the text "Terminal" and hitting enter on the top hit.
Now we can go ahead and execute the following command to get Homebrew installed.
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
The above command may come outdated by the time you're reading this article, if that's the case, please visit https://brew.sh/ for up to date instructions.
The installation will display all new directories and applications installed as part of Homebrew; you can go ahead and hit Enter to accept this and continue the installation.
Terminal will then prompt you for your macOS password; this is a normal part of installations of this kind. You can safely enter your password and hit enter.
Now I'd recommend making yourself a nice warm cup of tea, as this installation can take a few minutes. You can also consider donating to Homebrew as volunteers entirely run it, you can find out more information regarding this on their GitHub: https://github.com/Homebrew/brew#donations.
Installation Successful
Once we see these famous words in the console, we're all done with Homebrew!
We can verify everything is installed by simple running brew help.
PHP Tap
As with any package manager Homebrew has a system of locating packages through a variety of repositories. These are called taps within Homebrew; let's go ahead and add one for PHP.
brew tap henkrehorst/php
Now we've successfully added the new tap we can use Homebrew to install PHP 7.2 easily. As you can see by the package name, this is packaged explicitly for usage with Valet+ removing any of the complexities usually required when installing PHP on macOS.
brew install valet-php@7.2
Once again we can verify installation of PHP by executing php -v. You could see the following reported if everything was installed successfully.
Existing PHP Installations
In most cases developers with existing setups will have other PHP versions already installed, for ease of sake I recommend removing these prior to following these instructions as the conflict between PHP versions can cause issues. If you do not see the correct PHP version when running php -v it's most likely another PHP binary which has priority.
Composer
We now have a very capable package manager for macOS and we've installed PHP using it, now we need to install PHP's package manager composer.
Thanks to our good friend Homebrew this is as easy as:
brew install composer
Running composer will return the various commands available to be ran by this tool if installation was successful.
Valet+
Now onto the main event, we've got everything setup we need to install Valet+; as before this is incredibly easy.
Using the composer package manager we can go ahead and install weprovide/valet-plus as a global dependency, this enables us to use the valet command anywhere in the terminal.
composer global require weprovide/valet-plus
Now for probably the most complicated part of this whole tutorial, we need to update our bash profile to include the composer vendors folder. Updating the bash profile allows us to run binary files installed by composer without having to link them manually.
This tutorial was written for a fresh macOS installation we'll assume you're using bash. If you're using an alternative shell you'll need to edit the associated file for that shell; you can find out your shell by running echo $SHELL.
echo 'export PATH="$PATH:$HOME/.composer/vendor/bin"' >> ~/.bash_profile
source ~/.bash_profile
The command above adds the required path export to your ~/.bash_profile; it then loads the new contents into your current session.
Now we're able to access the valet binary installed by Composer; we first want to run the fix utility to diagnose and resolve any potential issues we may have in our installation. This command may ask for your password.
valet fix
The fix command has a large amount of output that's not all relevant to a successful installation; I would ignore the majority of the output from this command and only revisit if you have issues with a subsequent step.
The time has come, we're ready to have Valet install the necessary dependencies to create an easy to use development environment.
valet install
Once we see the Valet installed successfully text we're ready to move on.
Setting password for root user failed
If you see this error during your installation, there is no need to panic; this is a standard error with the MySQL installation associated with Valet. Typically this error is due to the MySQL@5.7 version not being linked correctly; we can resolve this by executing the following:
You only need to execute this if your installation failed to set the root user's password.
brew link mysql@5.7 --force
valet install
Verify installation
Valet+ sets up a local proxy to route all *.test requests back to localhost, this means we no longer need to edit the /etc/hosts file for every new website we wish to host.
To verify everything is working lets go ahead and attempt to ping a local test domain.
ping -c1 foobar.test
Creating ~/Sites directory
Now we've got all the tools installed we're ready to go ahead and create a directory to serve all of our Magento installations from. I promote the usage of Sites within your home directory. However, you can change this to your personal preference.
Once we've created the directory, we then go ahead and park the directory. Parking the directory tells valet to serve any subfolder as a web application automatically.
mkdir ~/Sites
cd ~/Sites
valet park
Install Magento 2
We've got two options for our installation composer and git based. Depending on your purpose for this installation you'll want to use the appropriate installation method.
Please note in both installations we use the folder magento2; this is the folder name that Valet will use for the domain name as magento2.test.
Composer based
See: (Contributor) Clone the Magento repository
This uses the composer binary to install all required dependencies for the Magento 2 installation automatically; this is best used for quick installations and merchant sites.
composer create-project --repository=https://repo.magento.com/ magento/project-community-edition magento2
This will require authentication keys for repo.magento.com; these can be retrieved from your Magento.com account.
Git based
https://devdocs.magento.com/guides/v2.3/install-gde/prereq/dev_install.html
The git based installation is best used when making contributions to the core product or when developing on 3rd party extensions.
git clone git@github.com:magento/magento2.git
cd magento2
composer install
Database creation
Now you have all the required files installed on your local system we can go ahead and create a new database for your installation.
valet db create magento2
Now we can use the Magento 2 setup GUI to complete the installation by visiting: http://magento2.test/setup.
Debugging
If the site didn't load when you visited the above URL then something is going wrong with your installation, there's a few common problems I've seen from all the great people who have followed my tutorial.
Nginx check
Sometimes the configuration file for ElasticSearch is not correctly created during installation, this can cause a complete failure of the instance. To check if you have this issue run the following:
sudo nginx -t
If this wonderful command informs you there is an issue with the elasticsearch.conf file you may just need to create an empty file here, you can do this by running
sudo touch /usr/local/etc/nginx/valet/elasticsearch.conf
Setup GUI
Now we can start moving through the Magento 2 installation.
Step 1: Readiness Check
Valet+ is pre-configured to be fully supported by Magento 2.3; so this step should pass first time.
Step 2: Add a database
We need to tell Magento where to store all information associated with our installation, we earlier created a database called magento2 that we can use for this step.
- Database Server Host:
localhost - Database Server Username:
root - Database Server Password:
root - Database Name:
magento2
Step 3: Web Configuration
Now we configure the store address and admin address. The store address will be completed with the host name automatically, so shouldn't require any further changes. I typically modify the admin address for local development, so it's easier to remember.
Step 4: Customize Your Store
You can set some basic configuration in this customisation step, such as the time zone currency and language. You can also disable specific modules included in your installation under the "Advanced Modules Configurations" section.
Step 5: Create Admin Account
Create a new admin account to enable you to manage your store.
Step 6: Install
The final step, we're ready to complete the Magento installation. Simply click the inviting orange button "Install Now"
Success!
Your installation is now completed, you're free to login and configure your Magento instance. Time to enjoy your crazy fast and simple local development environment for Magento 2.
I hope you found this tutorial beneficial and easy to follow. However, if you run into an issues please feel free to post a comment below and I'll try my best to diagnose and resolve your issues.
