This post originally featured on the Echo & Co. blog.
There’s nothing quite like setting up everything on your Mac for Drupal (or other PHP) development in a way that things just work and don’t need constant fiddling. This guide will walk you through using Homebrew to install Apache, PHP, and MySQL for a “MAMP” development environment. We’ll also use DNSMasq and Apache’s VirtualDocumentRoot to set up “auto-VirtualHosts,” and add a firewall rule to allow the default http port 80 to be used without running Apache as root.
At the conclusion of this guide, you’ll be able to create a directory like ~/Sites/project and access it at http://project.dev without editing your /etc/hosts file or editing any Apache configuration. You’ll also be able to use xip.io with auto-VirtualHosts for accessing your sites on other devices in your local network.
We also configure PHP and MySQL to allow for enough flexibility for complex operations generally only reserved for development and not production.
The OS X operating system comes with Apache and PHP pre-installed, and I’ve previously recommended utilizing them to some degree for getting a local PHP development environment on your Mac. Since then, the community around Homebrew has improved dramatically and I now recommend that our developers at Echo & Co. use Homebrew exclusively for all components.
If you’ve not already install Homebrew, you can follow the instructions at brew.sh, or simply run the following command:
1 2 3
Also of note, if you do not have
git available on your system, either from Homebrew, Xcode, or another source, you can install it with Homebrew now (if you already have it installed, feel free to skip this step to keep the version of
git you already have):
Since OS X already comes with PHP and Apache, we’ll want to make sure that our
brew-installed versions appear in the shell path before the built-in ones. The following command adds logic to your ~/.bash_profile to ensure the Homebrew directory is in the beginning of $PATH.
The following commands will download and install the latest version of MySQL and do some basic configuration to allow for large imports and a couple other miscellaneous configuration changes.
1 2 3 4 5 6 7 8 9 10 11
Now we need to start MySQL using OS X’s launchd, and we’ll set it to start when you login.
1 2 3 4 5
By default, MySQL’s root user has an empty password from any connection. You are advised to run
mysql_secure_installation and at least set a password for the root user.
Start by stopping the built-in Apache, if it’s running, and prevent it from starting on boot. This is one of very few times you’ll need to use
Apache is not in the default repository of Homebrew formulas, nor are some dependencies, so we use the
brew tap command to add other formula repositories.
We’ll install Apache 2.2 with Apr and OpenSSL from Homebrew as well instead of utilizing the built-in versions of those tools.
We’ll be using the file ~/Sites/httpd-vhosts.conf to configure our VirtualHosts, so we create necessary directories and then include the file in httpd.conf.
1 2 3 4 5 6 7 8
We’ll create a folder for our logs in ~/Sites as well.
Now to fill in the contents of ~/Sites/httpd-vhosts.conf that we included in httpd.conf earlier. Note that this is one command to copy and paste! Start with
USERHOME through the second
EOF has a single copy and paste block for the terminal.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
Run with port 80
You may notice that httpd.conf is running Apache on port 8080, but the
The following single command will create the file /Library/LaunchDaemons/co.echo.httpdfwd.plist as root, and owned by root, since it needs elevated privileges.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
This file will be loaded on login and set up the 80->8080 port forward, but we can load it manually now so we don’t need to log out and back in.
The following is for the latest release of PHP, version 5.5. If you’d like to use 5.3, 5.4 or 5.6, simply change the “5.5” and “php55” values below appropriately. (Note: if you use 5.3, the OpCache extension instructions are different. They will be posted below after the instructions for newer versions.)
Start by adding the PHP tap for Homebrew. PHP 5.3 needs an additional tap, so skip the second command if you are using 5.4 or higher.
1 2 3 4
Install PHP and mod_php. This command will also load the PHP module in the httpd.conf file for you.
Add PHP configuration to Apache’s httpd.conf file.
1 2 3 4 5 6
Set timezone and change other PHP settings (this is a single command).
sudo is needed here to get the current timezone on OS X (in previous versions of OS X it wasn’t needed, I’m not sure why it is now).
Add a PHP error log; without this, you may get Internal Server Errors if PHP has errors to write and no logs to write to (this is a single command; be sure to copy and paste the lines containing
USERHOME through the last
EOF as a single command).
1 2 3 4
This weird little “hack” is needed to fix a permissions problem with using
The OpCache extension will speed up your PHP environment dramatically, and it’s easy to install for 5.4 and higher. If you are looking to install PHP 5.3, skip this block.
Skip this block unless you are using PHP 5.3. Because there is no php53-opcache Homebrew formula, we can install it with
pecl and replicate the same configuration file.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
And continue with steps for all PHP versions: give OpCache some more memory to keep more opcode caches.
Start Homebrew’s Apache and set to start on boot.
1 2 3
I’ve covered this before, but we’ll list the commands here again for completeness. This example will have any DNS request ending in .dev reply with the IP address 127.0.0.1.
1 2 3 4 5
Because DNS services run on a lower port, we need to have this run out of /Library/LaunchDaemons, so we do need to use
sudo for the initial setup.
1 2 3
With DNSMasq running, configure OS X to use your local host for DNS queries ending in .dev
1 2 3
Great! So, what did I do?
We set up Apache to run on boot on port 8080 with mod_php with auto-VirtualHosts for directories in the ~/Sites folder. The OS X firewall will forward all port 80 traffic to port 8080, so we don’t have specify the port number when visiting web pages in web browsers. MySQL is installed and set to run on boot as well. DNSMasq and some OS X configuration is used to direct any hostname ending in .dev to the local system to work in conjunction with Apache’s auto-VirtualHosts.
What do I do now?
You shouldn’t need to edit the Apache configuration or edit /etc/hosts for new local development sites. Simply create a directory in ~/Sites and then reference that foldername + .dev in your browser to access it.
For example, use
drush to download Drupal 7 to the directory ~/Sites/firstproject, and it can then be accessed at http://firstproject.dev/ without any additional configuration. A caveat – you will need to uncomment the line in Drupal’s .htaccess containing “RewriteBase /” to work with the auto-VirtualHosts configuration.
What about this xip.io thing?
If your Mac’s LAN IP address is 192.168.0.10, you can access sites from any other device on your local network using http://firstproject.192.168.0.10.xip.io/. You can test a websites on your Mac with your phone/tablet/etc. Pretty great, right?
What if this “auto-VirtualHost” doesn’t work for me?
If you need to create a manual VirtualHost in Apache because the auto-VirtualHost does not work for your configuration, you may need to declare it before the auto-VirtualHosts if you’re also going to use .dev as the TLD. Otherwise the auto-VirtualHost block will be accessed first.