Part one of a two part series to set up an Apache/PHP development environment on macOS
This article is targeted towards web developers who want an Apache web server install as part of their development environment setup on their Mac.
If you?re a PHP developer, then this article is a pre-requisite to the next article which will walk you through installing PHP using Homebrew and PECL. A link to that article can be found at the bottom of this page.
As a developer, I used to rely on the version of Apache that came pre-loaded with the OS on my MacBook Pro. With the ever changing security rules in macOS, I?ve decided to change my whole approach and instead disable the distributed version of Apache and use a setup entirely from Homebrew. This new approach allows more flexibility for versioning and will continue to work across all macOS versions.
These instructions work the same for macOS 10.13 High Sierra and 10.14 Mojave. I?ve not tested on prior versions of macOS, but it should work similarly. Also, you don?t have to start with a fresh OS install to use this article, but I?ve been seeing some weird things happen when upgrading to Mojave vs a fresh install (e.g. completely missing the mod_deflate.so module extension file entirely after the upgrade). I recommend a fresh install, but if you?re braving an upgrade instead, be prepared to chase down some files and paths.
Let?s get started!
Get the Latest OS Updates
If you?ve just done a fresh OS install, you probably won?t need to do this.
Install Xcode
If you?re not interested in installing the entire Xcode app that?s fine, the Homebrew install command will install the basic Xcode Command Line Tools that it needs. However I recommend the full install especially if you?re running Mojave. To do this you can run the following command from terminal.
xcode-select –install
Install Homebrew
The following command will install Homebrew.
(Please note the following command is a single line that has wrapped due to page width constraints in Medium. Make sure to copy the entire line).
$ ruby -e “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)”
Create Apache Log File Directories
Apache comes pre-configured with its own log directories, but we?re going to create our own ?/usr/local/log/? folder so they?re easy to find when we need to. If you?re going to move to the next article to install PHP, we?ll be using this same log file location for the PHP logs too, and have all the logs in one place.
Follow these steps to create the appropriate directories and set their permissions. Disregard any ?already exists? messages you might get.
$ sudo mkdir /usr/local/log$ sudo mkdir /usr/local/log/httpd$ sudo chgrp -R staff /usr/local/log/httpd$ sudo chmod -R ug+w /usr/local/log/httpd/
Install and Configure Apache
macOS 10.13 High Sierra and 10.14 Mojave come with Apache pre-installed. However, instead of using the delivered version we?re going to install Apache via Homebrew and then configure it to run on port 80.
If you already have the pre-installed Apache running, it will need to be shutdown first and any auto loading scripts removed. It doesn?t hurt to run both of the following commands, even on a fresh install.
(Please note the second command is a single line that has wrapped due to page width constraints in Medium. Make sure to copy the entire line).
$ sudo apachectl stop$ sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist 2>/dev/null
Now install the new version of Apache provided by Homebrew.
$ brew install httpd
Once that?s complete, run the following command to start the Apache service and make sure that it restarts automatically at login.
$ brew services start httpd
You?ve now installed Homebrew?s version of Apache and configured it to autostart on reboot. It should already be running, so you should be able to point your browser at http://localhost:8080 and see a simple header that says, ?It works!?.
Note, we?re currently pointed to port 8080. We?re going to change that in the following steps. Now that we have a working web server, we?ll want to make some configuration changes so it works more to our liking ? or really just my liking ;-).
Let?s open up the Apache configuration file:
$ open -e /usr/local/etc/httpd/httpd.conf
Change the Listening Port
Scroll down and find the line that says, ?Listen 8080? and change it to;
Listen 80
Enable Useful Apache Modules
Next you can enable the following two handy Apache modules. You can search for the following two lines and uncomment them by removing the leading hashtag ?#?.
Hint: the deflate line is in the middle of the LoadModule section and the rewrite line is at the very bottom of the LoadModule section.
LoadModule deflate_module lib/httpd/modules/mod_deflate.soLoadModule rewrite_module lib/httpd/modules/mod_rewrite.so
Change Apache User and Group Settings
By default Apache runs as the user _www and group _www. In a bit we?re going to set our default document directory to a ?Sites? directory in our Home folder, and these user and group settings will cause you permission problems when trying to access files in your home directory.
Scroll about a third of the way down in your httpd.conf file and you?ll find two lines that set the User and Group that Apache will run under. Change these to match your user account. Replace your_username with your MacBook user name and use a group name of staff.
User your_usernameGroup staff
Set Apache Server Admin and Server Name
Find the ?ServerAdmin? line and enable it by removing the leading hashtag ?#? (if necessary) and then change the email to your own:
ServerAdmin [email protected]
Enable the Apache server name in the configuration by removing the leading hashtag ?#? and changing it to localhost:
ServerName localhost
Change the Document Root, Directory and Overrides
Next we?re going to change the document root for Apache. This is the folder where Apache looks to serve files from. By default the document root is configured as /usr/local/var/www. Because we?re creating a development environment and we want to avoid as many folder permission issues as possible, we?ll change the document root to a folder in our Home directory (which we?ll create shortly).
Continue to scroll down and find the DocumentRoot line. Change it to read:
DocumentRoot “/Users/your_username/Sites”
Next, you also need to change the tag reference right below the DocumentRoot line. This should be changed to point to your new document root as well:
<Directory “/Users/your_username/Sites”>;
In that same block you will find an AllowOverride setting. This should be changed from None to allow ?All? overrides:
AllowOverride All
Set Apache Error Log Location
Finally, we?re going to set the Apache error log location to the folder we created earlier. Scroll down a little farther and find the line for ?ErrorLog? and change it to read as follows:
ErrorLog “/usr/local/log/httpd/error_log”
Save and exit the text editor.
Create a Sites Folder
Use the following two lines to create a ?Sites? folder and add an index.html file to get us started:
(Please note the second command is a single line that has wrapped due to page width constraints in Medium. Make sure to copy the entire line).
$ mkdir ~/Sites$ echo “<h2>It Works in my Sites Folder</h2>;” > ~/Sites/index.html
Restart Apache
Now we?ll restart to make sure our configuration settings are correct:
$ sudo apachectl -k restart
Try browsing to your localhost at it?s new location: http://localhost
If this works and you see the message, ?It Works in my Sites Folder? then congratulations! You?ve got a new web server instance running on port 80.
If you receive an error, a likely cause could be the double-quotes used around directory entries in your httpd.conf file. Sometimes text editors will convert these to latin character-type quotes. These quotes are optional and can be removed. Try removing the double-quotes and restarting Apache again.
Part Two
If you?re a PHP developer and want to continue your development environment set up, then navigate to my article:
How to Install PHP on macOS 10.13 High Sierra and 10.14 Mojave using Homebrew and PECL.
There?s more!!
Upgrading to macOS 10.15 Catalina? Check out these articles on how to install set up your dev environment on the newest macOS:
- How to Install Apache on macOS 10.15 Catalina using Homebrew
- How to Install a PHP 7.2 on macOS 10.15 Catalina using Homebrew and PECL
