This brief guide focuses on getting a web development setup up and running on OSX 10.8 Mountain Lion. Working with already installed software and making the configuration changes manually the aim is to establish a clear method and consistent implementation that is easy to maintain and manage. There are many useful guides out there and an some excellent shell scripts to assist – however this guide is specific to our setup and helps to keep the underlying mechanics of whats happening under the hood as transparent as possible. By going through the manual steps the daily debugging and management of your server should be a whole lot easier.
In 10.8 the ability to manage the server instance has been removed from the system preferences sharing options. Without the GUI starting and stopping the server is achieved by running the following commands in your terminal. If you haven’t got it already, iTerm2 is a great terminal app – and it’s on the app store…
To start it
sudo apachectl start
To stop it
sudo apachectl stop
To restart it
sudo apachectl restart
To test your configuration
apachectl -t no "sudo" required this time.
To make sure Apache starts with each reboot run –
sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist
Using the commands to manage the apache server is ultimately the best way to manage your server. One of the drawbacks of the GUI was the lack of feedback when the server fails to start, by using the commands above we can more accurately debug an manage the server instance.
On the Mac traditionally there have been two document roots, a user root and a system root. If you upgraded to Lion you may already have a "Sites" folder in your user folder, a fresh install will be missing the folder.
To create your sites folder
The "~" character is a shortcut in the terminal to your user folder, mkdir is the command to "make a directory".
Next – configure your sites folder, to make the system manageable we will make minimal configuration here as the aim is to contain all configuration in one place – your sites folder. This will make managing your server instance easy since you wont need to hunt around system folders. Also keeping your configuration separated from the main files makes it easier to manage when upgrades are applied.
To edit your user apache config run the following, replacing USER with your username – if your not sure of the username to use run – "whoami" in the terminal.
sudo nano /etc/apache2/users/USER.conf
Copy and paste the following into the terminal
Include /*.conf, you will need to prefix the string "/*.conf" with the path to your site folder. Locate your "sites" folder in the finder, position your cursor in the terminal just on the "/" then simply drag and drop the folder form the finder to the terminal, this will put the correct path to your user folder into your config. You may end up with an extra space between the path and "/", just delete this
To save and close the file in nano, simply hit ctrl+x to quit answer yes to save.
You can then configure your virtual hosts basic setup –
sudo nano ~/Sites/vhost.conf
Then paste the following in, replace NAME with the default domain you want to associate with your development machine (optional – you can omit this line, however if your testing the config it will moan if that apache cant determine the servers domain name). Note – many guides will tell you to edit httpd.conf, however having your own modifications in once place outside the system files makes it a whole lot easier to maintain.
NameVirtualHost *:80 NameVirtualHost *:443 ServerName NAME:80 #optional - we live in a UTF-8 world, you may not... AddDefaultCharset UTF-8 #enable php support LoadModule php5_module libexec/apache2/libphp5.so
Now in your sites folder you can create your own *.conf files for each site you want to host locally, or simpler still you could put all your configurations in the one vhost.conf file. Note – this will not be read by your server instance untill you restart it (see above). Weather you run multiple files or one is down to personal preferance. There are many advantages of seperate configs per domain since this makes it easy to debug complex setups and even easier to simply move a few configs out the folder, if you want to disable a host.
You may need to make sure that directives can be over-riden – edit the main /etc/httpd.conf and change the following –
Options FollowSymLinks AllowOverride None Order deny,allow Deny from all
To the more permissive –
Options FollowSymLinks AllowOverride All #Order deny,allow #Deny from all
We recommend you structure this folder structure in a similar way as to how we would structure them on the enterprise linux server. The "httpdocs" folder will be the location for your site files. I tend to name my local development sites the same as the live sites and alias a suffixed domain to look at my local version.
vhost.conf - generic config domain.conf - specific virtual host sttings domain/httpdocs - web root domain/statistics - for the log files
basic domain.conf template as follows –
<VirtualHost *:80> ServerName DOMAIN ServerAlias PREFIX_DOMAIN ServerAdmin webmaster@DOMAIN DocumentRoot "/ROOT/DOMAIN/httpdocs" ErrorLog "/ROOT/DOMAIN/statistics/error_log" CustomLog "/ROOT/DOMAIN/statistics/access_log" common <Directory "/ROOT/DOMAIN/httpdocs"> Options Indexes FollowSymLinks MultiViews Includes AllowOverride All Order allow,deny Allow from all php_admin_value error_reporting 6143 php_admin_value display_errors 1 php_admin_value open_basedir "/ROOT/DOMAIN:/var/tmp:/usr/lib/php/pear:/tmp" </Directory> </VirtualHost>
The template above needs the following replaced with your equivalent settings –
the sites domain – we set this the same as the actual site so that we can easily run the site locally if the net is down and we want to test with a "e;live" like site.
This is the alias domain that your going to use to view the site locally, we normally often suffix the domain with a user related string.
the path to your sites root on the file system.
- Download the MySQL installer. You will need the 64bit version, first in the list. You do not need to register to download.
- Install MySQL
- Install Preference Pane
- Open System Preferences / MySQL
- Ensure the MySQL Server is running
- Enable MySQL to start automatically.
Add MySQL to your path by running the following in terminal –
To make mysql available from the command line edit the file "~/.bash_profile" and put the export line above inside it.
Note – by default MySQL will allow complete access to the server using the username "root" without a password from the localhost. To secure this account, run the following from your terminal (replacing the PASSWORD with one of your choice), note – the lowercase p before PASSWORD is required, not a typo…
mysqladmin -u root password PASSWORD mysqladmin -u root -pPASSWORD -h localhost password PASSWORD mysqladmin -u root -pPASSWORD reload history -c
The "history" line clears the password from your terminal history.
Configure MySQL – if you don’t want the defaults then run –
sudo cp /usr/local/mysql/support-files/my-default.cnf /etc/my.cnf
You can then edit the /etc/my.cnf to suit your applications needs. I found the following required to make MySQL play ball…
basedir = /usr/local/mysql datadir = /usr/local/mysql/data pid-file = /var/run/mysqld/mysqld.pid
Create the location for the pid file and make sure MySQL can access it…
sudo mkdir /var/run/mysqld sudo touch /var/run/mysqld/mysqld.pid sudo chown -R _mysql:wheel /var/run/mysqld
I found a reboot was in order to get MySQL to read the config.
It’s extremely simple to make a domain point to your local machine, this can be achieved by editing your "hosts" file, simply run
sudo nano /etc/hosts and add lines to the end of the file. The lines in this file are simply a list of IP address versus domain, separated by spaces. Changes to this file effect the machine immediately and are a quick and easy way to get domains pointing locally. The IP address 188.8.131.52 is reserved in DNS to refer to your local machine, therfore this is the IP address you should use to map a site to your machine. For example for my test web-engineer site I may hosts file would look like –
## # Host Database # # localhost is used to configure the loopback interface # when the system is booting. Do not change this entry. ## 127.0.0.1 localhost 255.255.255.255 broadcasthost ::1 localhost fe80::1%lo0 localhost 127.0.0.1 web-engineer.craig
Almost there – time for a test…
If you create a new file in your httpdocs folder – index.php (the default page) containing the following code we can validate the installation so far –
<?php phpinfo(); ?>
cd /etc sudo cp php.ini.default php.ini sudo chmod ug+w php.ini sudo chgrp staff php.ini sudo nano php.ini
Hit Crtl+w to search and look for the following settings and update as shown –
error_reporting = E_ALL | E_STRICT display_errors = On html_errors = On extension_dir = "/usr/lib/php/extensions/no-debug-non-zts-20090626" short_open_tag = On
Change all instances of
Very handy debugging tool if your going to get down and dirty with your debugging… More edits required from terminal.
sudo nano /etc/php.ini
Find the line:
;zend_extension="/usr/lib/php/extensions/no-debug-non-zts-20090626/xdebug.so" and remove the semicolon at the start
Recommend you configure your xdebug settings, then scroll to the end of the file and look for the
[xdebug] section. And use –
xdebug.var_display_max_children = 999 xdebug.var_display_max_data = 99999 xdebug.var_display_max_depth = 100
Restart apache, (see above), view your phpinfo file that xdebug is now loaded.
We need PEAR! This isn’t installed by default.
cd /usr/lib/php sudo php install-pear-nozlib.phar
Confgigure the include path –
nano /etc/php.ini find and update the line:
;include_path = ".:/php/includes" and change it to:
include_path = ".:/usr/lib/php/pear". Finally in your terminal run the following, note this will also add Firephp support!
sudo pear channel-update pear.php.net sudo pecl channel-update pecl.php.net sudo pear upgrade-all sudo pear channel-discover pear.firephp.org sudo pear install firephp/FirePHPCore
SSL – see http://www.cfdad.com/2012/12/12/creating-a-self-signed-ssl-cert-for-mac-osx-mountain-lion-apache/ for tips.
Debugging – having some fun with the configuration – don’t forget –
sudo apachectl -t -D DUMP_VHOSTS will tell you which configs are loaded and which hosts come from which file…