Mac OS X 10.11 El Capitan Localhost Setup

There are multiple methods and tools for developing web applications locally, I’ve always been a big fan of MAMP Pro due to it’s simplicity and it’s UI, it’s pleasant to use, very easy to setup and you’ll get running in no time. It does however have it’s downfalls and with OS X 10.11 now coming bundled with Apache what better time to try a new setup.

Note: This method is experimental only, when you upgrade the OS X you may loose your settings. Please use the following with caution.

When using third party programs you depend on it to have the latest versions of the development stack, but it can become out of date. By not using third party software you have full control over your setup, today I’ll be giving you a deep dive on how to setup your environment with the ability to have multiple PHP versions and virtual hosts. This article is for experienced developers who have experience using the command prompt.

Files you’ll be editing

To keep things simple I’ve listed out all the files you’ll need:

/private/etc/hosts
/etc/apache2/httpd.conf
/etc/apache2/extra/httpd-vhosts.conf

Step 1: Apache commands

As Apache is already installed you can start getting familiar with its commands straight away by opening up the command prompt and entering the following.

Start:

sudo apachectl start

Stop:

sudo apachectl stop

Restart:

sudo apachectl restart

Apache version:

httpd -v

After starting Apache you can test to see if the server is working in the browser by going to http://localhost you should see the text “It works!”. If your struggling to reach your site via this url you might need to add an alias in your /private/etc/hosts file, even though it should be there by default. Simply add 127.0.0.1 localhost on a new line and save.

osx-server-it-works

Note: Throughout the rest of this article whenever you see the string your_username being used please change it to match the username on your Mac.

Step 2: Configuring Apache

Now you have tested the server is working you need to configure it. To do this you need to open up the /etc/apache2/httpd.conf file in your favorite text editor. Before you do though make a quick backup just in case you make an error you can always revert to the original:

cp /etc/apache2/httpd.conf /etc/apache2/httpd.conf.backup

Now you have a backup you can go in and edit the file, I’ll be using the vim tool in my examples:

vim /etc/apache2/httpd.conf

There will be multiple areas you need to change in this file but I’ll break it down into small chunks detailing what each part does.

Enable modules and includes

The first set of configuration will be to enable some modules and an include which I’ve listed out below, to enable them simply remove the # symbol from the beginning of the line:

Search for the term vhost_alias_module:

LoadModule vhost_alias_module libexec/apache2/mod_vhost_alias.so

Search for the term rewrite_module:

LoadModule rewrite_module libexec/apache2/mod_rewrite.so

Search for the term php5_module:

LoadModule php5_module libexec/apache2/libphp5.so

Search for the term Virtual hosts:

Include /private/etc/apache2/extra/httpd-vhosts.conf

Some applications require the mod_rewrite module which provides a rule-based rewriting engine to rewrite requested URLs on the fly.

While Virtual Hosts allow you to run more than one website on a single machine, you can also point them to individual IP addresses or domain names of your choice which I’ll cover in more depth later on.

Document root

This is the directory where you’ll be serving your documents from, it’s entirely down to personal preference, traditionally it’s named public_html or htdocs. In this example we’ll be pointing it to a new folder called Sites under our username.

Search for the term DocumentRoot and change the path so it reads:

DocumentRoot "/Users/your_username/Sites"

You’ll also need to change the <Directory> tag on the line below to the same path:

<Directory "/Users/your_username/Sites">

Within the same <Directory> block change the AllowOverride setting to read:

AllowOverride All

This setting will allow any .htaccess files to override the default settings.

User and group

Apache is now pointing to your Sites folder, however you also need to tell Apache to run under a different username and group otherwise you will face permission problems when trying to access the files in your home directory. By default Apache runs under the _www username and the _www group.

Search for the term User _www and change it to read:

User your_username
Group staff

Notice the Group is set to staff this is because all users are members of the staff group. If your user is setup differently you may have to change this parameter to your individual requirements. A quick and easy way to see what group your username is assigned to is by running ls -la within the home directory in the command prompt which will display the group column against your folders and files.

Directory index

You’ll need to add index.php to your directory index which sets the files that Apache will serve if a directory is requested.

Search for the term <IfModule dir_module> and change it to read:

<IfModule dir_module>
    DirectoryIndex index.html index.php
</IfModule>

Don’t forget to save the file at this stage, you’ll be coming back to this file shortly.

Create a sites folder

Now that you have your initial configuration in place you need to create your Sites folder to house your documents. You’ll also create your first html file to ensure everything is working as intended:

mkdir ~/Sites
echo '<h1>Hello World!</h1>' > ~/Sites/index.html

You now need to restart apache so that your changes will take effect, it’s important to note that whenever a change is made it won’t take effect until Apache is restarted.

sudo apachectl restart

Now if you open up your browser and head to http://localhost you should see the message you created.

osx-server-hello-world3

PHP info

It’s also a good time to check that PHP is working. The easiest way to do this is by using the built in phpinfo() which will detail out your PHP configuration including what version your using:

cd ~/Sites
echo "<?php phpinfo(); ?>" > ~/Sites/info.php

If you open up your browser and head to http://localhost/info.php you should see something similar to the below screenshot detailing out the PHP configuration:

osx-server-phpinfo

If this is working you can proceed with the next step, if not you’ll need to backtrack through the configuration and ensure it’s all correct.

Step 3: MySQL

MySQL is a missing component in OS X 10.11 and needs to be dowloaded from the MySQL site or alternatively for ease of use you can install it through Homebrew. Either installation method will work, however in this article I’ll be showing you how to install it through Homebrew.

First you need to install Homebrew if you haven’t already:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

To check everything is running correctly you can run:

brew doctor

If you have Homebrew already installed ensure its all up to date by running:

brew update

Now you can go ahead and install MySQL by running:

brew install mysql

It’s that simple! You can then use the following commands to run MySQL:

Start:

mysql.server start

Stop:

mysql.server stop

Restart:

mysql.server restart

When working with databases I always find it useful to use a GUI and would recommend downloading Sequel Pro (it’s free) which provides an easy to use interface. Once installed you can access MySQL through the following connection settings:

osx-server-sqlpro4

Remember to make sure your MySQL server is running otherwise you won’t be able to connect.

Step 4: Virtual hosts

Earlier you loaded in the necessary modules for virtual hosts, you now need to configure these by opening the following file:

vim /etc/apache2/extra/httpd-vhosts.conf

This file already contains some instructions for you, it’s important to note that these entries are matched in order. Because you changed your DocumentRoot earlier you need to add in support for this as your first entry:

<VirtualHost *:80>
    DocumentRoot "/Users/your_username/Sites"
    ServerName localhost
</VirtualHost>

You can then add further entries below like so:

<VirtualHost *:80>
    DocumentRoot "/Users/your_username/Sites/my-site"
    ServerName my-site.com
</VirtualHost>

When adding entries into your virtual hosts file you will also need to add them into your Mac hosts file. To do this open up the following file:

vim /private/etc/hosts

In here you’ll need to add a new entry that matches your ServerName from the virtual hosts file and then save:

127.0.0.1 my-site.com

Lastly you need to restart apache so that your virtual host entries take effect:

sudo apachectl restart

Navigating to my-site.com should now display your website. You’ll have to add a index.html or index.php file within the /Users/your_username/Sites/my-site/ folder otherwise you’ll just get nothing showing.

That sums up the standard setup for a localhost environment. If you want to be able to manage multiple PHP versions and enable additional features like SSI (Server Side Includes) keep on reading below where I’ll be covering these topics.

Multiple PHP versions

Having a flexible localhost environment is key when your working with multiple applications as each have their own prerequisite. We can utilise Homebrew by installing multiple PHP versions and switching between them as needed.

Homebrew has a selection of PHP versions we can pick from, of course you can choose which versions you want to install. Before we do there are a few dependencies that are required which are outlined on their GitHub page, simply enter the following into the command prompt:

brew tap homebrew/dupes
brew tap homebrew/versions
brew tap homebrew/homebrew-php

Now you can install the individual PHP versions like so:

brew install php55
brew unlink php55
brew install php56
brew unlink php56

You will notice the unlink option which will allow you to use multiple PHP versions. The last step is to link Apache to the PHP version you want to use. To do this you need to open up /etc/apache2/httpd.conf and search for the term php5_module which needs commenting out like so:

#LoadModule php5_module libexec/apache2/libphp5.so

Right below this line we can add in our own, remember to only have 1 of them un-commented at a time:

# Brew PHP LoadModule, Edited
LoadModule php5_module /usr/local/opt/php55/libexec/apache2/libphp5.so
#LoadModule php5_module /usr/local/opt/php56/libexec/apache2/libphp5.so

As you have edited the Apache configurtion you’ll now need to restart Apache so that your changes take effect:

sudo apachectl restart

Each time you need to use a different version of PHP simply open up this file and amend as necessary.

Enabling SSI

To enable SSI there are a couple of extra configuration settings you need to add to Apache. First load in the mod_include module, to enable it simply remove the # symbol from the beginning of the line.

Search for the term include_module:

LoadModule include_module libexec/apache2/mod_include.so

Don’t forget to save the file. Next you need to configure Apache to parse .shtml files. This will allow the server to process content server side before its sent to the client. To do this you add the configuration to your .htaccess file within your site folder.

Create a .htaccess file if you don’t already have one within:

/Users/your_username/Sites/my-site/

Then open up the file and enter the following configuration and save:

AddType text/html .shtml
AddHandler server-parsed .html
AddHandler server-parsed .shtml
Options Indexes FollowSymLinks Includes

Now we just need to restart apache and everything should be working as expected:

sudo apachectl restart

Tips

There are a lot of commands and paths in the command prompt to remember which can be tricky when you’re first starting out. To overcome this I use alias which allows me to assign shortcuts for common commands. These are added into your .bash_profile located in your home directory.

If you don’t already have one you can easily create one by entering the following into the command prompt:

cd ~/
touch .bash_profile

Now you can enter your alias, below is an example of how my .bash_profile looks, you’ll notice I’m using Sublime Text to open up my files:

# Ensure user-installed binaries take precedence
export PATH=/usr/local/bin:$PATH

# Alias
alias hosts='sublime /private/etc/hosts'

# Server alias
alias apache-httpd='sublime /etc/apache2/httpd.conf'
alias apache-vhosts='sublime /etc/apache2/extra/httpd-vhosts.conf'
alias apache-start='sudo apachectl start'
alias apache-stop='sudo apachectl stop'
alias apache-restart='sudo apachectl restart'
alias mysql-start='mysql.server start'
alias mysql-stop='mysql.server stop'
alias mysql-restart='mysql.server restart'

Once saved you might need to re-start the command prompt. Then to run the command you simply type in the alias name for example:

apache-start

Wrap up

Hopefully you’re now set up! It can be a little daunting when configuring a server for the first time which is why it’s always good practice to make backups of files when doing something like this. However it’s a rewarding exercise and once it’s setup you’ll barely touch it again, plus you gain an insight into how Apache servers are setup.