PREFACE
These are my personal notes that I use every time I reformat or get a new computer. I’ve curated these instructions over the course of 4 years, so they are littered with links to relevant source material and have been stripped down to the exact actionable steps I need to take to get up and running. As such, this post is mostly for my own benefit, and I will regularly update it as my process changes (usually with each new OS X release).
These instructions have been updated to specifically support OS X Mavericks (10.9), but will work with Mountain Lion (10.8), Lion (10.7), Snow Leopard (10.6), and Leopard (10.5). Running 10.4 or lower? You should probably upgrade 🙂
I might write some follow-up posts about using this setup to create a killer local WordPress Multisite installation, and also porting your dev environment contents to live in DropBox. If so, I’ll link them up here.
Why not just use MAMP?
If you’re wondering, I like to set up my local environment, instead of using MAMP, because I prefer to have it always available. I never liked having a separate application running just so I could access my local dev setup. Also, it has always bothered me that MAMP bundled its own copies of PHP, Apache and MySQL when the only missing component that doesn’t come pre-loaded with OS X is MySQL.
Help, I’m stuck!
It’s worth mentioning here that I’m not a very smart guy, which is why I’ve kept these detailed notes for the last 4 years. These instructions work for me, but they might not work for you. If you get stuck with an issue, I suggest googling around and sharing what you discover here in the comments. It will likely be much faster than asking me for help, and will benefit everyone who reads this (me included)!
A Quick Word about my Terminal Commands
In many of the terminal instructions I use my custom bash shortcut “sub” to open a given file in Sublime Text 2 via command line. You can substitute “sub” for your text editor of choice (e.g. “vi” for Vim, or “mate” for TextMate, or “subl” for the standard Sublime shortcut).
Install MySQL
Follow these steps, in order:
- Download DMG installer from http://www.mysql.com/downloads/mysql/
- Install MySQL
- Install MySQL auto-start
- Install MySQL pref pane
- Then, configure MySQL:
- In Terminal:
sub ~/.profile
- Add this line to the file:
export PATH="/usr/local/bin:/usr/local/sbin:/usr/local/mysql/bin:$PATH"
- Save and close the file.
- Add this line to the file:
- In Terminal:
source ~/.profile
- Finally, configure MySQL socket (because OS X is looking in the wrong directory): http://www.davewidmer.net/blog/2009/03/upgrading-to-leopard-broke-my-local-development/
Configure PHP
These steps are really only to keep you sane while testing uploads and such in your projects:
- In Terminal:
sudo cp /etc/php.ini.default /etc/php.ini
- In Terminal:
sub /etc/php.ini
- Update
upload_max_filesize
to something like 64MB (L891 in OS 10.8) - Update
post_max_size
to something like 64MB (L740 in OS 10.8) - Save and close
Configure Apache
Update httpd.conf to enable PHP5 and Virtual Hosts:
- In Terminal:
sub /etc/apache2/httpd.conf
- Uncomment the include for PHP5 (L117 in OS 10.8, L111 in older releases)
- Uncomment the include Virtual Hosts (L477 in OS 10.8, L623 in older releases)
- Save and close the file.
- If you’re running OS X 10.7 or earlier, you’ll also need to enable “Web Sharing” in System Preferences > Sharing.
Setup Virtual Hosts (http://foundationphp.com/tutorials/vhosts_leopard.php):
Update: If you’d rather have “*.dev” dynamically mapped to “~/Sites/www/*”, check out this great article on Apache zero-config development. Then, follow this article on using DNSmasq to redirect all .dev traffic locally.
For the example below, you’ll want to replace “rzen.dev” with your own custom URL, and “username” with your own OS X username.
- In Terminal:
sub /private/etc/hosts
- Add the following line to the file:
- 127.0.0.1 rzen.dev
- Save and close the file.
- In Terminal:
sub /private/etc/apache2/users/username.conf
- Add the following lines to the file:
-
<Directory "/Users/username/Sites/"> Options FollowSymLinks Indexes MultiViews AllowOverride All Order allow,deny Allow from all </Directory> <VirtualHost *:80> ServerName rzen.dev DocumentRoot "/Users/username/Sites/" </VirtualHost>
-
- Save and close the file.
- Finally, flush the DNS cache & Restart Apache (you’ll want to do this any time you edit your hosts file and virtual hosts setup):
- In Terminal:
dscacheutil -flushcache
- In Terminal:
sudo apachectl restart
- In Terminal:
In my setup I’ve registered rzen.dev to point to my ~/Sites/ folder, rzen.wp to point to ~/Sites/wordpress/, and rzen.php to point to ~/Sites/phpMyAdmin. This means I’ve created a separate pointer for each domain in my hosts file, and a separate <VirtualHost> container for each in my apache .conf file.
Apache Error Notes
Later, if apache ever goes south and starts spitting 403 Forbidden, or some other error, check the error log. You can open it from inside Terminal: sub /var/log/apache2/error_log
If the problem is “Symbolic link not allowed or link target not accessible”, confirm that your symlinked folder, it’s parent directory, et al, have sufficient permissions for owner and group (http://forums.dropbox.com/topic.php?id=40992#post-337655).
Upgrading OS X?
Be aware that with every upgrade OS X is likely to overwrite your edits to Apache’s httpd.conf file. Specifically, you’ll probably need to edit /etc/apache2/httpd.conf
once again and uncomment the lines for including PHP (L118) and enabling Virtual Hosts (L478).
This has at least been true both for upgrading to OS X Mountain Lion (10.8) and OS X Mavericks (10.9), and probably true in upgrading to releases before those.
The Optional (but recommended) Bits
Install Sequel Pro
This app is amazing, and it works brilliantly for manipulating both local and remote databases. And it’s free!
Download Sequel Pro
Install phpMyAdmin (if you hate living in the future and using Sequel Pro)
- Download latest version of phpMyAdmin from http://www.phpmyadmin.net/home_page/index.php
- Unzip to ~/Sites/phpMyAdmin/
- Rename config.sample.inc.php to config.ing.php
- On L36 change
$cfg['Servers'][$i]['AllowNoPassword']
to true - By default, your login will be root with no password
Install WordPress
- Download the latest version of WordPress from http://wordpress.org/download/
- Unzip to ~/Sites/wordpress/
- Create a new database for your install via phpMyAdmin to use during installation
- Database server will be localhost
- Username will be root
- Password will be blank
- Pro-Tip: Once installed, edit wp-config.php add
define('FS_METHOD','direct');
somewhere before the “That’s All, stop editing here” comment. This will enable direct access to the file system when running automatic updates and make your local dev experience mui guapo.
Install Git
Visit http://git-scm.com/ and download + install the latest version. Done.
Install SVN
For some reason, beginning in Mountain Lion (OS X 10.8), Apple stopped packaging SVN with Mac OS. So, you’ll need to download “XCode Command Line Tools” separately by signing in as a Developer (after registering for a free account using your Apple ID) here: https://developer.apple.com/downloads/index.action.
Alternatively, you can download SVN directly from WanDisco: http://www.wandisco.com/subversion/download#osx. I recommend using 1.7+.
Enable SSL
If you ever have need to test a site or service locally using https://, my co-worker @jtsternberg has written up a wonderfully detailed step-by-step of his experience doing just that. You can read it here: How to set up SSL with OSX Mountain Lion’s built-in Apache
Leave a Reply