There are many cases where having a local development environment is helpful and it is a relatively straightforward thing to do, even if you are new to development. However, the blessing and the curse is that there are many, many tutorials out there attempting to show you how. This series of posts will aim to walk through some basic steps with detail, as well as pass on some tips and tricks for setting up your own local dev box.
First, what do I mean by a local development environment? This is a setup on your computer which allows you to code and tweak and test in a safe environment. It’s a great way to hammer on a new application with relatively low stakes. I am currently installing dev environments for two purposes: to test some data model changes I want to make on an existing Drupal site and to learn a new language so I can contribute to an application. For the purposes of this series, we’re going to focus on the AMP stack – Apache, MySQL and PHP – and how to install and configure those systems for use in web application development.
Apache is the web server which will serve the pages of your website or application to a browser. You may hear Apache in conjunction with lots of other things – Apache Tomcat, Apache Solr – but generally when someone references just Apache, it’s the web server. The full name of the project is the Apache HTTP Server Project.
PHP is a scripting language widely used in web development. MySQL is a database application also frequently used in web development. “Stack” refers to the combination of several components needed to run a web application. The AMP stack is the base for many web applications and content management systems, including Drupal and WordPress.
You may have also seen the AMP acronym preceded by an L, M or W. This merely stands for the operating system of choice – Linux, Mac or Windows. This can also refer to installer packages that purport to do the whole installation for you, like WAMP or MAMP. Employing the installer packages can be useful, depending on your situation and operating system. The XAMPP stack, distributed by Apache Friends, is another example of an installer package designed to set up the whole stack for you. For this tutorial though, we’ll step through each element of the stack, instead of using a stack installer.
So, why do it yourself if there are installers? To me, it takes out the mystery of how all the pieces play together and is a good way to learn about what’s going on behind the scenes. When working on Windows, I will occasionally use a .msi installer for an individual component to make sure I don’t miss something. But installing and configuring each component individually is actually helpful.
Tips
Before we begin, let’s look at some tips:
- You will need administrative rights to the computer on which you’re installing.
- Don’t be afraid of the command line. There are lots of tutorials around the web on how to use the basic commands – for both Mac (based on UNIX) and Windows. But, you don’t need to be an expert to set up a dev environment. Most tutorials give the exact commands you need.
- Try, if possible, to block off a chunk of time to do this. Going through all the steps may take awhile, from an hour to an afternoon, especially if you hit a snag. Several times during my own process, I had to step away from it because of a crisis or because it was the end of the day. When I was able to come back later, I had some trouble remembering where I left off or the configuration options I had chosen. If you do have to walk away, write down the last thing you did.
- When you’re looking for a tutorial, Google away. Search for the elements of your stack plus your OS, like “Apache MySQL PHP Mac OSX”. You’ll find lots, and probably end up referencing more than one. Use your librarian skills: is the tutorial recent? Does it appear to be from a reputable source? If it’s a blog, are there comments on the accuracy of the tutorial? Does it agree with the others you’ve seen?
- Once you’ve selected one or two to follow, read through the whole tutorial one time without doing anything. Full disclosure: I never do this and it always bites me.
Let’s get going with Recipe 1 – Install the AMP Stack on Mac OS X
Install the XCode Developer Tools
First, we install the developer tools for XCode. If you have Mac 10.7 and above, you can download the XCode application from the App Store. To enable the developer tools, open XCode, go to the XCode menu > Preferences > Downloads tab, and then click on “Install” next to the developer tools. This tutorial on installing Ruby by Moncef Belyamani has good screenshots of the XCode process.
If you have Snow Leopard (10.6) or below, you’ll need to track down the tools on the Apple Developer Downloads Page. You will need to register as a developer, but it’s free. Note: you can get pretty far in this process without using the XCode command line tools, but down the road as you build more complicated stacks, you’ll want to have them.
Configure Apache and PHP
Next we need to configure Apache and PHP. Note that I said “configure”, not “install”. Apache and PHP both come with OS X, we just need to configure them to work together.
Here’s where we open the Terminal to access the command line by going to Applications > Utilities > Terminal.
Once Terminal is open, a prompt appears where you can type in commands. The ” ~ ” character indicates that you are at the “home” directory for your user. This is where you’ll do a lot of your work. The “$” character delineates the end of the prompt and the beginning of your command.
Type in the following command:
cd /etc/apache2
“cd” stands for “change directory”. This is the equivalent of double-clicking on etc, then apache2, if you were in the Finder (but etc is a hidden folder in the Finder). From here, we want to open the necessary file in an editor. Enter the following command:
sudo nano httpd.conf
“sudo” elevates your permission to administrator, so that you can edit the config file for Apache, which is httpd.conf. You will need to type in your administrator password. The “nano” command opens a text editor in the Terminal window. (If you’re familiar with vi or emacs, you can use those instead.)
The bottom of your window will show the available commands. The “^” stands for the Control key. So, we want to search for the part to change, we press Control + W. Enter php and press Enter. We are looking for this line:
#LoadModule php5_module libexec/apache2/libphp5.so
The “#” at the beginning of this line is a comment, so Apache ignores the line. We want Apache to see the line, and load the php module. So, change the text by removing the #:
LoadModule php5_module libexec/apache2/libphp5.so
Save the file by press Control + O (nano calls this “WriteOut”) and press Enter next to the file name. The number of lines written displays at the bottom of the window. Press Control + X to exit nano.
Next, we need to start the Apache server. Type in the following command:
sudo apachectl start
Now, go to your browser and type in http://localhost. You should see “It Works!”
Apache, as mentioned before, serves web files from a location we designate. By default, this is /Library/Webserver/Documents. If you have Snow Leopard (10.6) or below, Apache also automatically looks to username/sites, which is a convenient place to store and work with files. If you have OS 10.7 or above, creating the Sites folder takes a few steps. On 10.7, go to System Preferences > Sharing and click on Web Sharing. If there’s a button that says “Create Personal Web folder”, it has not been created, go ahead and click that button. If it says, “Open Personal Website folder”, you’re good to go.
On 10.8, the process is a little more involved. First, go to the Finder, click on your user name and create your sites folder.
Next, we need to open the command line again and create a .conf file for that directory, so that Apache knows where to find it. Type in these commands:
cd /etc/apache2/users ls
The ls at the end will list the directory contents. If you see a file that’s yourusername.conf (ie, mfrazer.conf) in this directory, you’re good to go. If you don’t, it’s easy to create one. Type the following command:
sudo nano yourusername.conf
So, mine would be sudo nano mfrazer.conf. This will create the file and take you into a text editor. Copy and past the following, making sure to change YOURUSERNAME to your user name.
<Directory "/Users/YOURUSERNAME/Sites/"> Options Indexes MultiViews AllowOverride None Deny from all Allow from localhost </Directory>
The first directive, Options, can have lots of different…well, options. The ones we have here are Indexes and MultiViews. Indexes means that if a browser requests a directory and there’s no index.html or index.php file, it will serve a directory listing. Multi-Views means that browsers can request the content in a different format if it exists in the directory (ie, in a different language). AllowOverride determines if an .htaccess file elsewhere can to override the configuration settings. For now, None will indicate that no part can be overridden. For Drupal or other content management systems, it’s possible we’ll want to change these directives, but we’ll cover that later.
The last two lines indicate that traffic can only reach this directory from the local machine, by typing http://localhost/~username in the browser. For more on Apache security, see the Apache documentation. If you would like to set it so that other computers on your network can also access this directory, change those last two lines to:
Order allow,deny Allow from all
Either way, press Control + O to save the file and Control + X to exit. Restart Apache for the changes to take effect using this command:
sudo apachectl restart
You may also be prompted at some point by OS X to accept incoming network connections for httpd (Apache); I would deny these as I only want access to my directory from my machine, but it’s up to you depending on your setup.
We’ll test this setup with php in the next step.
Test PHP
If you want to check php, you can create a new text document using your favorite text editor. Type in:
<?php phpinfo(); ?>
Save the file as phpinfo.php in your username/sites directory (so for me, this is mfrazer > Sites)
Then, point your browser to http://localhost/~yourUserName/phpinfo.php You should see a page of information regarding PHP and the web server, with a header that looks like this:
MySQL
Now, let’s install MySQL. There’s two ways to do this. We could go to the MySQL downloads page and use the installers. The fantastic tutorials at Coolest Guy on the Planet both recommend this, and it’s a fine way to go.
But we can also use Homebrew, mentioned previously on this blog, which is a really convenient way to do things as long as we’re already using the command line.
First, we need to install homebrew. Enter this at the command prompt:
ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"
Next, type in
brew doctor
If you receive the message: “Your system is raring to brew.” You’re ready to go. If you get Warnings, don’t lose heart. Most of them tell you exactly what you need to do to move forward. Correct the errors and type in brew doctor again until you’re raring to go. Then, type in the following command:
brew install mysql
That one’s pretty self-explanatory, no? Homebrew will download and install MySQL, as of this writing version 5.6.10, but pay attention to the download to see the version – it’s in the URL. After the installation succeeds, Homebrew will give some instructions on finishing the setup, including the commands we discuss below.
I’m going to pause for a second here and talk a little about permissions and directories. If you get a “permission denied” error, trying running the command again using “sudo” at the beginning. Remember, this elevates your permission to the administrator level. Also, if you get a “directory does not exist” error, you can easily create the directory using “mkdir”. Before we move on, let’s try to check for a directory you’re going to need coming up. Enter:
cd /usr/local/var
If you are successfully able to change to that directory, great. If not, type in
sudo mkdir /usr/local/var
to create it. Then, let’s go back to our home directory by typing in
cd ~
Now, let’s continue with our procedure. First, we want to set up the databases to run with our user account. So, we type in the following two commands:
unset TMPDIR mysql_install_db --verbose --user=`whoami` --basedir="$(brew --prefix mysql)" --datadir=/usr/local/var/mysql --tmpdir=/tmp
The second command here installs the system databases; ‘whoami’ will automatically replace with your user name, so the above command should work verbatim. But it also works to use your user name, with no quotes, (ie –user=mfrazer).
Next, we want to run the “secure installation” script. This helps you set root passwords without leaving the password in plain text in your editor. First we start the mysql server, then we run the installation scripts and follow the prompts to set your root password, etc:
mysql.server start sudo /usr/local/Cellar/mysql/5.6.10/bin/mysql_secure_installation
After the script is complete, stop the mysql server.
mysql.server stop
Next, we want to set up MySQL so it starts at login. For that, we run the following two commands:
ln -sfv /usr/local/opt/mysql/*.plist ~/Library/LaunchAgents launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist
The ln command, in this case, places a symbolic link to any .plist files in the mysql directory into the LaunchAgents directory. Then, we load the plist using launchctl to start the server.
One last thing – we need to create one more link to the mysql.sock file.
cd /var/mysql/ sudo ln -s /tmp/mysql.sock
This creates a link to the mysql.sock file, which MySQL uses to communicate, but which resides by default in a tmp directory. The first command places us in the directory where we want the link (remember, if it doesn’t exist, you can use “sudo mkdir /var/mysql/” to create it) and the second creates the link.
MySQL is ready to go! And, so is your AMP stack.
But wait, there’s more…
One optional tool to install is phpMyAdmin. This tool allows you to interact with your database through your browser so you don’t have to continue to use the command line. I also think it’s a good way to test if everything is working correctly.
First, let’s download the necessary files from the phpMyAdmin website. These will have a .tar.gz extension. Place the file in your Sites directory, and double-click to unzip the file.
Rename the folder to remove the version number and everything after it. I’m going to place the next steps below, but the Coolest Guy on the Planet tutorial referenced earlier does a good job of this step for OS 10.8 (just scroll down to phpMyAdmin) if you need screenshots.
Go to the command line and navigate to your phpMyAdmin directory. Make a directory called config and change the permissions so that the installer can access the file. This should looks something like:
cd ~/username/sites/phpMyAdmin mkdir config chmod o+w config
Let’s take a look at that last command: chmod changes the permissions on a file. The o+w sets it so users who are not the directory’s owner can write to the file.
Now, in your browser, go to http://localhost/~username/sites/phpmyadmin/setup and follow these steps:
- Click on New Server (button on bottom)
- Click on Authentication tab, and enter the root password in the password field.
- Click on Save.
- Click on Save again on the main page.
Once the setup is finished, go to the Finder and move the config.inc.php file from the config directory into the main phpmyadmin directory and delete the config directory. So in the end, it looks like this:
Now, go to http://localhost/~username/sites/phpmyadmin in your browser and login with the root account.
You are ready to go! In future parts of this series, we’ll look at building the AMP stack on Windows and adding Drupal or WordPress on top of the stack. We will also look at maintaining your environment, as the AMP stack components will need updating occasionally. Any other recipes you’d like to see? Do you have questions? Let us know in the comments.
The following tutorials and pages were incredibly useful in writing this post. While none of these tutorials are exactly the same as what we did here, they all contain useful pieces and may be helpful if you want to skip the explanation and just get to the commands:
- Coolest Guy on the Planet AMP Tutorials (10.8, 10.7/10.6) by Neil Gee
- Using Homebrew to Support Drupal on OSX by Ron Golan
- Uninstall/Re-install MySQL from stackexchange.com