Install Magento 2 Locally on a Mac
I recently spent some time creating a local Magento 2 environment on my Macbook Pro. It was an adventure, and I felt like there were a number of details missing from the tutorials I had followed.
Many of the tutorials were either out of date, vague, or made assumptions on my level of technical knowledge. So I’d like to share what I learned and walk you through the step-by-step process of creating a local Magento 2 instance on your computer running macOS 10.15.
There are a few things to be aware of before you get started:
- Check out the most current dependencies for Magento 2 before installing anything using this link: https://devdocs.magento.com/guides/v2.3/install-gde/system-requirements-tech.html
- If you are running macOS 10.15, MySQL 5.7 is currently not supported which means when we get to installing MySQL we will install v8.0 and need to make a few minor changes in the MySQL configuration file.
Step 1 – Installing Homebrew
To begin we will install homebrew which will be used to install the components necessary to run our localhost. To install homebrew you will open up Terminal and then copy the following command
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
or you can go to their website and follow the instructions there : https://brew.sh/
Once homebrew finishes installing you can now see what services you may already have, you should not have any, using this command
brew services list
Step 2 – Installing httpd (Apache)
Now that we have homebrew installed we can start installing our Magento dependencies. First, let us begin the installation by entering the following code.
brew install httpd
Once homebrew finishes the installation process you should be able to use our brew services list command to see its status. It should say httpd stopped To start your Apache server you will enter in the following command
brew services start httpd
To test if this worked go to your web browser and enter in localhost:8080 to the URL bar and you should see this:
Step 3 – httpd Configuration
Now that we have successfully launched Apache on your machine we will go forward and begin to edit our Apache configuration settings.
Changing Localhost URL
We will be looking for the httpd.conf file located at
/usr/local/etc/httpd
Open httpd.conf with your preferred text editor and look for the following:
listen 8080
To make our URL nicer to use we will want to change this to:
listen 80
This will make it so you only have to type localhost into your URL to pull up your Apache server.
Changing DocumentRoot Directory
Next, you will edit will be the DocumentRoot and directory. By default, it should say:
DocumentRoot “/usr/local/var/www”
I’d recommend you change the path to be in your user directory so it’s easy to access. You can do this by replacing what is above with the location of a directory named www inside your current users home directory:
DocumentRoot "/Users/[your user]/www" <Directory "/Users/[your user]/www">
If you do this correctly it should look similar to this
Allowing Overrides
The next configuration setting you’ll need navigate to is:
AllowOverride none
Magento 2 Requires that this be set to the following
AllowOverride all
This configuration should now look like this
Enabling the rewrite_module
Now, we need to enable the rewrite_module. Navigate to:
#LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so
We need to uncomment this module so that Magento 2 may use this. We do this as follows:
LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so
Once configured this is what this section should look like.
Setting our User and Group
Finally, you’ll want to specify the local user and their group that you are using for your directory By default, the two variables will look like:
User _www Group _www
If you are unsure of what your user and user group is, then navigate back to your home directory in the terminal (you can use cd with no arguments to do this) and enter the following
ls -al
This will list everything in your current directory and you should see something like this The important part to look for is in the middle in this case my user is joshuaduda and my user group is staff We now can go ahead and enter this into your configuration document
User [your user] Group [your user group]
It will look something like this
Testing
We are now done with editing this configuration file for now so you can save/close it before navigating back to your home directory (cd with no arguments) where we will make the directory we specified as the DocumentRoot Directory. Once there, enter the following:
mkdir www
Now, let’s test to see if this worked. Enter in your own path into this command:
Echo “Hello World” > /Users/www/index.html
Now we will want to restart our Apache server so that the changes will take effect
brew services restart httpd
Once this is complete you can go to your web browser and enter in localhost as the URL; this should be the result:
Congratulations you’ve just set up Apache!
Step 4 – Installing and Setting up MySQL
I want to make a note quickly here as I had mentioned before. Magento 2 currently does not support MySQL 8.0 and MySQL 5.7 does not work with macOS 10.15.
If you are running on macOS 10.14 and don’t plan to update you can install the proper version of MySQL using the following command:
brew install mySQL@5.7
Note that if you are doing this, do not install a newer version of MySQL. Also later in this tutorial there will be a step you can skip (I will point this out).
If you are on macOS 10.15 or installing the latest version of MySQL you will type the following to install MySQL Database
brew install mySQL
Once MySQL installs you can now see that it is a brew service by using the command:
brew services list
You can start MySQL with the command:
brew services start mysql
Preparing MySQL for Magento 2
Once MySQL is running you can type the following in your terminal:
mySQL -u root
For now, your root account has no password, you can change this in the future but for now, we will focus on setting up your database for your magento2 instance.
Now that we are in your MySQL database, let’s start by creating our database by entering the following:
create database magento2
The next step will be to create a user account. This isn’t always necessary but it will avoid some potential installation issues down the road:
CREATE USER 'admin'@'localhost' IDENTIFIED WITH mysql_native_password BY 'admin123';
Feel free to create a different username (‘admin’) or password (‘admin123’), just note that I will be using these values for our installation and that this is only setting an admin account for your MySQL instance, not Magento.
You need to give permissions to this user so that Magento 2 can have access to your MySQL instance and create and update the magento2 database. Enter the following to grant these permissions:
GRANT ALL PRIVILEGES ON *.* to 'admin'@'localhost';
Once you have done this you can use the following to flush the privileges so that your database is up to date:
flush privileges;
That is everything we need to set up in MySQL so go ahead and log out:
exit;
This will log you out of MySQL and take you back to your main terminal. MySQL should be ready for Magento 2 installation
Step 5 – Installing PHP 7.3
Notice that I specified the version here. Currently, Magento 2 does not support PHP 7.4 so you need to be careful when installing PHP that you do not install an incompatible version.
Install PHP 7.3 by entering the following command:
brew install php@7.3
this may take a little while and feel like it is frozen but be patient as homebrew runs parts of the installation in the background
Now once homebrew finishes the installation, you can check your brew services list – you should see php@7.3 stopped. To start PHP on your localhost type:
brew services start php@7.3
Configuring httpd for php@7.3 module
If you try to run PHP on Apache as we are right now, PHP would not run. That is why we need to go back to our httpd configuration file found in:
/usr/local/etc/httpd
In httpd.conf we need to navigate back to the rewrite_module and add the correct PHP module below it by entering the following:
LoadModule php7_module /usr/local/opt/php@7.3/lib/httpd/modules/libphp7.so
It should now look like this:
There is also one more section that we need to modify: navigate to DirectoryIndex. Specify index.php in the directory index by adding to:
DirectoryIndex index.html
So it matches:
DirectoryIndex index.php index.html
The result should be:
Once this is done go ahead and save this configuration file.
Testing to see if PHP is running on Apache
One last step in setting up PHP and that is testing to see if it all works. We need to navigate back to the directory you created previously (/www) and create a new PHP document in here and call it index.php Inside index.php copy the following code
Now we need to restart are Apache server once more to read the new configurations
brew services restart httpd
and now if you go to your web browser and enter “localhost”, you should see this:
If this is being displayed and you see Version 7.3.* you should be all set to move on to the next step!
Step 6 – Installing Composer and Magento 2
We want to install Composer our package builder which will allow us to download the Magento 2 environment onto your machine.
Installing Composer
We need to make sure we are in our local Apache directory:
/Users/[your user]/www
Once you are here, copy the following lines of commands and paste them into your terminal
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" php -r "if (hash_file('sha384', 'composer-setup.php') === 'e0012edf3e80b6978849f5eff0d4b4e4c79ff1609dd1e613307e16318854d24ae64f26d17af3ef0bf7cfb710ca74755a') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;" php composer-setup.php php -r "unlink('composer-setup.php');"
You can also use the current installation method found at: https://getcomposer.org/download/
Once that completes you should see a file name composer.phar We can now install composer by typing
php composer.phar install
Installing Magento 2 Using Composer
Now that composer is installed we can go ahead and install Magento 2 to our Apache server. I will give you the command for both Magento Open Source and Magento Commerce, although I realize you have to have the proper authentication keys from Magento.
If you do not know how to get your magento 2 authentication keys follow the tutorial at this link: https://devdocs.magento.com/guides/v2.3/install-gde/prereq/connect-auth.html
The Magento Open Source command is
composer create-project --repository-url=https://repo.magento.com/ magento/project-community-edition magento2
Or for Magento Commerce
composer create-project --repository-url=https://repo.magento.com/ magento/project-enterprise-edition magento2
You can also find these commands at: https://devdocs.magento.com/guides/v2.3/install-gde/composer.html
If these commands don’t work, an easy workaround is to try replacing “composer” for the following
php composer.phar ...
When you begin the installation you will be prompted to enter in a username and a password Your username will be your public key and your password will be your private key
note that for security reasons the terminal will not display any values for password
Once this is complete we are almost done! Here is the part where we do final setup and fix compatibility issues.
Step 7 – Permissions and MySQL 8.0 Compatibility Fix
Permissions
To start we’ll ensure that we allow Magento commands to execute. To do this you need to navigate to your magento2 folder inside of your local Apache directory:
cd ~/www/magento2
Once there, we need to enter a simple command that will allow Magento 2’s commands to run:
chmod a+x bin/magento
Errors
If you tried to run your Magento 2 installation process now, you would fall into a couple of different errors. Below are the methods I used to fix these issues – hopefully, they’ll be useful to you!
Increasing PHP memory_limit
First, we’ll give Magento the correct amount of ram so that there are no memory errors on installation. To do this we will need to access the php.ini file. To find that, type:
php --ini
You are looking for the loaded configuration file:
Mine is located at /usr/local/etc/php/7.3/php.ini. I used a text editor to find a line containing:
memory_limit
The default value will not be enough for Magento 2 to set up so we will need to change this to either 4G – or if you end up still having memory issues -1 which will give Magento 2 as much memory as it needs.
memory_limit = 4G
This is what it should look like
You can now save and close this document
Fixing MySQL 8.0 Compatibility Errors
If you are on macOS 10.15 or using MySQL 8.0 you will need to make the following changes inside Magento 2 to work properly on your machine
First, we need to navigate to the file Mysql.php found in:
~/magento2/vendor/magento/framework/DB/Adapter/Pdo
Open up Mysql.php with your preferred editor and find:
case 'smallint':
Directly below this line, you need to add:
case 'smallint unsigned':
You also will need to do a similar thing after:
case 'int':
Directly below adding:
case 'int unsigned':
This section of the file should now look like this:
Once you’ve completed these steps, you may save and close this document then navigate back to the magento2 directory inside of your Local Apache directory.
Step 8 – Launching the Site
Let’s begin by restarting all of our brew services so that we can be sure our changes have all been applied:
brew services restart httpd brew services restart mysql brew services restart php@7.3
There are currently two ways of going about installation. Magento recommends using the command-line since the web setup wizard will be deprecated once Magento 2.4 launches.
Note that if you run into any issues, Magento will list the error it has run into. A great thing to do if that happens is to try copying and pasting the error code into your web browser and see what comes up. The good thing about Magento is there is a large community around it using many different machines meaning you can find people similar issues who have gotten very helpful feedback.
The Command-line Way
Again make sure you are inside of your magento2 directory and then you will enter in the following:
bin/magento setup:install --base-url=http://localhost/magento2/ --db-host=localhost --db-name=magento2 --db-user=admin --db-password=admin123 --admin-firstname=Magento --admin-lastname=Admin --admin-email=user@example.com --admin-user=admin --admin-password=admin123 --language=en_US --currency=USD --timezone=America/Chicago --use-rewrites=1
This should work if you’ve set everything up exactly as I have and if you’d like to learn more about each of these options you can find that at https://devdocs.magento.com/guides/v2.3/install-gde/install/cli/install-cli-install.html#instgde-install-cli-magento
If this runs correctly you will see this:
Once this completes it will display your admin URL which will allow you access the backend. You are all set now! To see your website enter the following into your web browser
localhost/magento2
You should see your Magento 2 frontend now! To access the backend you will add your unique admin URL to the end of your URL, for example, my admin URL is
localhost/magento2/admin_4cwub1
You will be directed to the admin login screen now.
The username and password will be what you set it to during installation – in our case username will be admin and password will be admin123
The Setup Wizard Method
To access this method we actually need to go to our internet browser and type in the following localhost/magento2/setup First, you’ll agree to the terms and agreement for Magento.
Next Magento will double check your compatibility.
If you run into issues here you will have to do some troubleshooting although Magento gives you good feedback to work off of.
Next, we will set up our database. All we need to enter is the database host, which will be localhost, the MySQL username, and password, which will be admin and admin123, and lastly the name of the database we created, which will be magento2.
Now we will set up our store’s web address, you can change this to be anything you’d like although that will require some more steps of configuration that I will not cover and can sometimes cause issues.
For the admin address, you can change this, but it’s recommended you keep this randomized for security reasons.
Now, we’ll set up our store default timezone, currency, and language:
Next, we will make our admin account for our website. In this case, I just used a generic username and email but feel free to make any of this whatever you’d like:
Now that You’ve completed all of the other steps in the Magento setup wizard process you can proceed and click install.
Again remember, if you run into any issues the error codes provided and the Magento community are a very great troubleshooting resource
Now that you’ve finished up you can type the URL into your browser and your website will load!
localhost/magento2
To access the backend remember to copy the admin URL that Magento 2 has given you at the conclusion of the installation process. I’ll use the URL provided by the setup wizard:
localhost/magento2/admin_4cwub1
Conclusion
I hope that this guide is useful and will make your efforts to set up Magento 2 on your Mac a bit easier. If you get stuck, there are a number of resources and troubleshooting tips available within the Magento 2 Community and Magento Support. Or comment below and we’ll give it a shot! If you are unsure of what to do next now that you have Magento 2 installed here’s some suggestions to get started.
Leave a Reply
Want to join the discussion?Feel free to contribute!