= NOTE: THIS HOW-TO GUIDE IS IN PRODUCTION AND SHOULD NOT BE USED = == Installing and configuring critical helper packages == Being able to send and receive email is often part of the web application development process. == Installing PHP, Apache, and MySQL == PHP and Apache should be already installed. You can check your version of PHP and Apache with the following two, separate commands in a Terminal window (Applications > Utilities > Terminal). Hopefully you're running php5. If not, you'll need to install it: http://php.net/downloads.php: {{{ php -i }}} If you receive any errors or are unable to complete the following commands, then you may need to install Apache from Unix source into /Library/Apache2: http://httpd.apache.org/download.cgi#apache22 {{{ cd /etc/apache2 httpd -v }}} It's unlikely that your mac has mysql installed already, so you need to download the latest version from here: http://dev.mysql.com/downloads/mysql. Download and run the mysql-5.5.xxx-xxx.pkg file, which will automatically install to /usr/local. To put a control in your system preferences pane and start mysql, in the .dmg file, run MySQL.prefPane by double-clicking. Start mysql and also ensure that mysql always starts on boot. == Configuring the environment == The goal of the configuration is to make it as easy as possible to setup a new development environment for a new project. Each new project will have a unique, non-public domain name based on the name of the workstation. Each project will have a corresponding directory in your home directory where you can place php and other files to be served by apache. In this example, let's assume the workstation is named "junior" and the username is "admin." A new project called "mayfirst" would have the development domain name: mayfirst.local (below we will edit the /etc/hosts file so that this non-public domain name will resolve to the development workstation). Create a projects directory in your home directory: {{{ mkdir ~/projects }}} There are a few tweaks that must be done before OS X will work with our setup: {{{ echo "export PATH=\$PATH:/usr/local/mysql/bin" >> ~/.profile sudo mkdir /var/mysql sudo ln -s /tmp/mysql.sock /var/mysql/mysql.sock }}} We need to do a lot of configuration to apache, which is almost all in the file /etc/apache2/httpd.conf. Start by commenting-out this line: {{{ #ServerRoot "/usr" }}} and uncommenting the following line: {{{ LoadModule php5_module libexec/apache2/libphp5.so }}} and commenting-out this first line and adding the second: {{{ #DocumentRoot "/Library/WebServer/Documents" }}} Just below in the same file, /etc/apache2/httpd.conf, modify the default directory settings: {{{ Options All Options FollowSymLinks AllowOverride All Order deny,allow Deny from all Allow from 127.0.0.1 }}} There is now an entire block that must be commented-out regarding DocumentRoot. Insert a "#" in front of everything all the way to and including . It starts with: {{{ }}} Also modify these lines so that they are as they appear below, which are sprinkled throughout the rest of this very long file and then save: {{{ #Include /private/etc/apache2/extra/httpd-userdir.conf Include /private/etc/apache2/extra/httpd-vhosts.conf Include /private/etc/apache2/extra/httpd-default.conf }}} Apache can be configured so that it dynamically sets the document root based on the domain name. Now, we want to drastically modify /etc/apache2/extras/httpd-vhosts.conf. It's best to actually create a clean file. Do this by backing up the old one and then editing a clean file with the same name: {{{ mv /etc/apache2/extras/httpd-vhosts.conf /etc/apache2/extras/httpd-vhosts.conf.back sudo nano /etc/apache2/extras/httpd-vhosts.conf }}} While in editing mode, add this, save, and close: {{{ AllowOverride All VirtualScriptAlias /Users/admin/projects/%1/cgi-bin/ VirtualDocumentRoot /Users/admin/projects/%1/web/ }}} This is the penultimate step to configure Apache. On a mac, you should be able to keep apache running without any issues with performance on your computer. But just to reduce traffic, since this not a live webserver, modify /etc/apache2/extras/httpd-mpm.conf with the following: {{{ StartServers 1 MinSpareServers 1 MaxSpareServers 2 MaxClients 10 MaxRequestsPerChild 100 }}} Reload Apache so these changes take effect by going to system preferences > sharing and enabling web sharing. == Steps to create a new project == With your environment setup, you can easily start a new project by following these steps: * Choose a name for the project. In this example, we'll choose the name mayfirst (and remember - in our example the computer name is junior). * Create the mysql database with: {{{ mysql -u root -p -e "CREATE DATABASE mayfirst; GRANT ALL ON mayfirst.* to 'mayfirst'@'localhost' identified by 'mayfirst';" }}} * Add a new domain to your /etc/hosts file. Add it to the line that starts with 127.0.1.1 (you can safely create the line if it doesn't exist). For example: {{{ 127.0.0.1 localhost 127.0.1.1 mayfirst.local }}} * Change into your projects directory: {{{ cd ~/projects }}} * Clone and checkout your source files via git {{{ git clone git@git.mayfirst.org:/mayfirst.git }}} * OR create your project folders with: {{{ mkdir ~/projects/mayfirst mkdir ~/projects/mayfirst/web mkdir ~/projects/mayfirst/cgi-bin }}} NOTE: If you are developing a Drupal project, you will need to edit your .htaccess file. There's a line that says the following: {{{ # If your site is running in a VirtualDocumentRoot at http://example.com/, # uncomment the following line: RewriteBase / }}} You will want to uncomment the RewriteBase directive as shown above. Now you are ready to begin. You can start placing files in your project's web directory and access your project at the URL: !http://mayfirst.local/ == Keeping files in sync == If you are working on a database driven project (like Drupal) it can be difficult to keep your database and (in the case of Drupal) your files directory in sync. A bash script like the following one can help - by providing an easy way to synchronize your development platform with the live site: {{{ #!/bin/bash echo "Synchronizing database." ssh @ "mysqldump -u -p " | mysql -u -p echo "Synchronizing files." rsync -av --exclude '*/settings.php' --exclude '.svn*' --exclude '*/.svn*' --exclude 'sites*' @: }}}