Prepare the Box

1. Turn off unneeded services on the server box. Open System Preferences and select Sharing.
   • turn on remote login
   • (optional) turn on Screen Sharing
   • Turn off everything else - especially Web Sharing and File Sharing
2. Install XCode. This provides tools that MacPorts uses to build the programs for your machine. You can get XCode for free from the app store. It’s a huge download. Note that after you download it, you have to run the installer. It may launch XCode when the install is done, but you can just Quit out of it.
3. Install MacPorts. You can download the installer from http://www.MacPorts.org/install.php (make sure you choose the .dmg that matches the version of MacOS you are running). Run the installer and get ready to start typing.
4. Now it’s time to make sure MacPorts itself is up-to-date. Open terminal and type
   1. sudo port selfupdate
   2. password: <enter your admin password>
   MacPorts will contact the mother ship and update itself.
• If you're not familiar with sudo, you will be soon. It gives you temporary permission to act as the root user for this machine. Every once in a while during this process you will need to type your admin password again.
5. May as well get into the habit of updating the installed software while we’re at it. Type
   1. sudo port upgrade outdated
   and you will most likely see a message that looks like an error but really says that there was nothing to upgrade. No biggie.
   • Make a habit of running these commands regularly. One of the reasons you're doing this whole thing is to make sure your server stays up-to-date. This is how you do it.

Install Apache

1. Now it’s time to get down to business. All the stuff we’ve installed so far is just setting up the tools to make the rest of the job easier. Let’s start with Apache!
   1. sudo port install apache2
   • This may take a little while. It’s actually downloading code and compiling a version of the server tailored to your system. First it figures out all the other little pieces Apache needs and makes sure they’re all installed correctly. Hop up and grab a sandwich, or, if you're really motivated, do something else productive while you wait.
2. When the install is done, you will see a prompt to execute a command that will make Apache start up automatically when the computer is rebooted. Usually you will want to do this. The command has changed in the past, so be sure to check for the message in your terminal window. As of this writing, the command is:
   1. sudo port load Apache2
3. Create an alias to the correct apachectl. apachectl is a utility that allows you to do things like restart Apache after you make changes. The thing is, the built-in Apache has its own apachectl. To avoid confusion, you can either type the full path to the new apachectl every time, or you can set up an alias. Aliases are commands you define. In this case you will define a new command that executes the proper apachectl.
   1. In your home directory (~/) you will find a file called .profile - if you didn’t have one before, MacPorts made one for you. Note the dot at the start. That makes the file invisible; Finder will not show it. In terminal you can see it by typing
      1. ls -a ~/
      You will get back a list of all the files in your home directory, including the hidden ones that start with ..
   2. Edit ~/.profile and add the following line:
      1. alias apache2ctl='sudo /opt/local/apache2/bin/apachectl'
      • Edit how? See below for a brief discussion about editing text files and dealing with file permissions.
      • ~/.profile isn't the only place you can put the alias, but it works.
   3. You need to reload the profile info for it to take effect in this terminal session.
      1. source ~/.profile
   4. Now anywhere in the docs it says to use apachectl, just type apache2ctl instead, and you will be sure to be working on the correct server.
4. Start Apache:
   1. apache2ctl start
   You might see a warning or two, probably a notification about the server's name. That's fine.
5. Test the Apache installation. At this point, you should be able to go to http://127.0.0.1/ and see a simple message: “It works!”
6. MILESTONE - Apache is up and running!

Install PHP

1. Use MacPorts to build PHP 5:
   1. sudo port install php5 +pear
   • You could install the MySQL extensions to PHP now (sudo port install php5-mysql), but that will cause MySQL to be installed as well. It’s no biggie, but I like to make sure each piece is working before moving on to the next. It makes problem-solving a lot easier. So, let’s hold off on that.
   • +pear adds an industry-standard way to load other PHP addons later.
2. Choose your php.ini file. There are a couple of different options that trade off security for convenience (error reporting and whatnot). As of this writing there is php.ini-development (more debugging information, less secure) and php.ini-production. Copy the one you want to use and name it php.ini:
   1. sudo cp /opt/local/etc/php5/php.ini-development /opt/local/etc/php5/php.ini
   You will be editing this file a little bit later, but mostly it’s just a bunch of settings you’ll never need to understand.
3. Test the PHP install
   1. On the command line, type
      1. php -i
   2. A bunch of information will dump out. Hooray!
4. Now it’s time to get Apache and PHP talking to each other. Apache needs to know that PHP is there, and when to use it. There’s a lot of less-than-ideal advice out there about how to do this.
   1. httpd.conf is the heart of the Apache configuration. Mess this up, Apache won’t run. It’s important, therefore, that you MAKE A BACKUP (there’s actually a spare copy in the install, but you never rely on that, do you?)
      1. cd /opt/local/apache2/conf
      2. sudo cp httpd.conf httpd.conf.backup
   2. First run a little utility installed with Apache that supposedly sets things up for you, but actually doesn’t do the whole job:
      1. cd /opt/local/apache2/modules
      2. sudo /opt/local/apache2/bin/apxs -a -e -n "php5" libphp5.so
   3. The utility added the line in the Apache config file that tells it that the PHP module is available. It does not tell Apache when to use it. There is an extra little config file for that job, but it’s not loaded (as far as I can tell), and it’s not really right anyway. Let's take matters into our own hands.
      • It won't let me save! See below for a brief discussion about editing text files and dealing with permissions.
   4. Time to edit! Open /opt/local/apache2/conf/httpd.conf with permission to edit it. We need to add three lines; one to tell it that PHP files are text files (not strictly necessary but let’s be rigorous here), and two lines to tell it what to do when it encounters a PHP file.
      1. Search for the phrase AddType in the file. After the comments (lines that start with #) add:
         1. AddType text/html .php
      2. Search for AddHandler (it’s just a few lines down) and add:
         1. AddHandler application/x-httpd-php .php
         2. AddHandler application/x-httpd-php-source .phps
         The second of those is just to let you display PHP source code in a Web page without actually running it.
      3. Finally, we need to tell Apache that index.php is every bit as good as index.html. Search in the config file for index.html and you should fine a line that says DirectoryIndex index.html. Right after the html file put index.php:
         • Before:
           1. DirectoryIndex index.html
         • After:
           1. DirectoryIndex index.html index.php
      4. (Optional) As long as we’re in here, let’s make one more change for improved security. Search for the line that specifies the default options for Apache and remove Indexes:
         • Before:
           1. Options Indexes FollowSymLinks
         • After:
           1. Options FollowSymLinks
         This prevents outsiders from seeing a list of everything in a directory that has no index file.
      5. Save the file.
   5. Check the init file syntax by typing
      1. /opt/local/apache2/bin/httpd -t
      You will probably get a warning about the server’s name again, but that’s OK, as long as you see the magical Syntax OK message. If there is an error, the file and line number should be listed.
   6. Restart Apache:
      1. apache2ctl restart
5. Test whether PHP and Apache can be friends. We will modify the “It Works!” file to dump out a bunch of info about your PHP installation.
   1. Currently the default Apache directory is /opt/local/apache2/htdocs
   2. Start by renaming index.html to index.php:
      1. cd /opt/local/apache2/htdocs
      2. sudo mv index.html index.php
   3. Edit the file, and after the It Works! bit add a PHP call so the result looks like this:

      1. <html>

      2.     <body>

      3.         <h1>It works!</h1>

      4.         <?php echo phpinfo(); ?>

      5.     </body>

      6. </html>

   4. Save the file
   5. Go to http://127.0.0.1 - you should see a huge dump of everything you wanted to know about your PHP but were afraid to ask.
6. MILESTONE - Apache and PHP are installed and talking nice to each other.

Install and configure MySQL

1. Use MacPorts to install MySQL database and server and start it automatically when the machine boots:
   1. sudo port install mysql5-server
   2. sudo port load mysql5-server
2. Now we get to the trickiest part of the whole operation. There's nothing here that's difficult, but I've spent hours going in circles before, and I'm here so you won't find yourself in that boat as well. MySQL requires some configuration before it can run at all, and it can be a huge bother figuring out what’s going on if it doesn’t work the first time. We start by running a little init script:
   1. sudo -u _mysql mysql_install_db5
3. As with Apache, you can create a set of aliases to simplify working with MySQL. There are some commands you will run frequently; things get easier if you don’t have to type the full path to the command every time. Open up ~/.profile again and add the following three lines:
   1. alias mysqlstart='sudo /opt/local/share/mysql5/mysql/mysql.server start'
   2. alias mysql='/opt/local/lib/mysql5/bin/mysql'
   3. alias mysqladmin='/opt/local/lib/mysql5/bin/mysqladmin'
   When you're done, save and
   1. source ~/.profile
4. Start MySQL server:
   1. mysqlstart
5. Next we need to deal with making the database secure and setting the first all-important password. The most complete way to do this is running another utility that takes you through the decisions.
   1. /opt/local/lib/mysql5/bin/mysql_secure_installation
   The script offers to delete some test users and databases that in my experience are totally useless anyway. Take the advice offered and get rid of all that junk.
   Remember the password you set for the root user!
   • You now have a MySQL account named root which is not the same as the root user for the machine itself. When using sudo you will use the machine root password (as you have been all along), but when invoking mysql or mysqladmin you will enter the password for the database root account.
6. As with PHP above, MySQL has example config files for you to choose from. The config file can be placed in a bunch of different places, and depending on where you put it, it will override settings in other config files. If you follow this install procedure, you don’t actually need to do anything with the config files; we’ll just be using the factory defaults. But things will work better down the road if you choose a config that roughly matches the way the database will be used.
   1. Find where the basedir is. As of this writing it’s /opt/local, and that’s not likely to change anytime soon, but why take that for granted when we can find out for sure? Let's make a habit of finding facts when they're available instead of relying on recipes like this one.
      1. mysqladmin -u root -p variables
      2. password: <enter MySQL root user's password>
      A bunch of info will spew across your screen. At this moment, there are two interesting nuggets: basedir and socket. Make a note of them for later.
   2. Now it’s time to choose which example config file you want to start with. The examples are in /opt/local/share/mysql5/mysql/, and each has a brief explanation at the top that says what circumstances it’s optimized for. You can read those, or just choose one based on the name. If you have no idea how big your database is going to be, medium sounds nice. You can always swap it out later.
   1. sudo cp /opt/local/share/mysql5/mysql/my-medium.cnf <basedir>/my.cnf
   Fill in <basedir> with the basedir you learned in the previous step.
7. Test MySQL
   1. On the command line, type
      1. mysql -u root -p
      2. password: <enter MySQL root user's password>
      and enter the MySQL root user password when prompted. No errors? Cool. We’re done here. Type
      1. exit
      at the prompt.
8. MILESTONE - MySQL server is running and happily talking to itself.

Teach PHP where to find MySQL

1. The database is up and running; now we need to give PHP the info it needs to access it. There's a thing called a socket that the two use to talk to each other. Like a lot of things in UNIX the socket looks like a file.

   The default MySQL location for the socket is in /tmp, but MacPorts doesn’t play that way. There are a couple of reasons that /tmp is not an ideal place for the socket anyway, so we’ll do things the MacPorts way and tell PHP that the socket is not at the default location. To do this we edit /opt/local/etc/php5/php.ini.

   There are three places where sockets are specified, and they all need to point to the correct place. Remember when you saved the socket variable from MySQL before? Copy that line and then search in your php.ini file for three places where is says default_socket:

   1. pdo_mysql.default_socket = <paste here>
   2. . . .
   3. mysql.default_socket = <paste here>
   4. . . .
   5. mysqli.default_socket = <paste here>

   In each case the whatever = part will already be in the ini file; you just need to find each line and paste in the correct path.

2. While we’re editing the file, you may want to set a default time zone. This will alleviate hassles with date functions later.
3. Finally, we need to install the PHP module that provides PHP with the code to operate on MySQL databases.
   1. sudo port install php5-mysql
4. Restart Apache:
   1. apache2ctl restart
5. Test the connection.
   1. Typing
      1. php -i | grep -i 'mysql'
      Should get you a list of a few mysterious lines of stuff.
   2. Second test: The whole bag of marbles. You ready for this?
      
      1. In the Apache’s document root (where the index.php file you made before lives), create a new file named testmysql.php
      2. In the file, paste the following:
         

         1. <?php

         2. $dbhost = 'localhost';

         3. $dbuser = 'root';

         4. $dbpass = 'MYSQL_ROOT_PASSWRD';

         5. $conn = mysql_connect($dbhost, $dbuser, $dbpass);

         6. if ($conn) {

         7.     echo 'CONNECT OK';

         8. } else {

         9.     die ('Error connecting to mysql');

         10. }

         11. $dbname = 'mysql';

         12. mysql_select_db($dbname);

      3. Edit the file to replace MYSQL_ROOT_PASSWRD with the password you set for the root database user.
      4. Save the file.
   3. In your browser, go to http://127.0.0.1/testmysql.php
   4. You should see a message saying “Connection OK”
6. MILESTONE - Apache, PHP, and MySQL are all working together. High-five yourself, bud! You are an IT God!

Set up virtual hosts.

Finally, we will set up virtual hosts. This allows your server to handle more than one domain name. Even if you don't think you need more than one domain, it's a safe bet that before long you'll be glad you took care of this ahead of time.

We will create a file that tells Apache how to decide which directory to use for what request. There is an example file already waiting for us, so it gets pretty easy.

1. Tell Apache to use the vhosts file. To do this we make one last edit to httpd.conf. After this, all our tweaks will be in a separate file so we don’t have to risk accidentally messing something up in the master file.
   1. In /opt/local/apache2/config/httpd.conf, find the line that says
      1. #Include conf/extra/httpd-vhosts.conf
      and remove the #.
   2. The # told Apache to ignore the include command. Take a look at all those other files it doesn’t include by default. Some of them might come in handy someday...
   3. Save the file and restart Apache
   4. Test by going to your old friend http://127.0.0.1
   5. Forbidden! What the heck!?! Right now, that's actually OK. The vhosts file is pointing to a folder that doesn't exist and even if it did it would be off-limits. All we have to do is modify the vhosts file to point to a directory that actually does exist, and tell Apache it's OK to load files from there.
2. Before going further, it's probably a good idea to figure out where you plan to put the files for your Web sites. I've taken to putting them in /opt/local/www/domain.com/public/ - not through any particular plan, but /opt/local/www is the default location for phpMyAdmin and I just went with it. The public part is so you can have other files associated with the site that are not reachable from the outside.
3. Set up the default host directory
   1. Open /opt/local/apache2/conf/extra/httpd-vhosts.conf for editing.

   2. You will see two example blocks for two different domains. Important to note that if Apache can’t match any of the domains listed, it will default to the first in the list. This may be an important consideration for thwarting mischief.

      The examples provided in the file accomplish one of the two things we need to get done — they tell Apache what directory to use for each domain, but they do nothing to address what permissions Apache has in those directories. A lot of people put the permissions stuff in the main httpd.conf, but why not keep it all in one place and simplify maintenance while we reduce risk?

      Here's an example:

      1. <VirtualHost *:80>

      2.     ServerAdmin [email protected]

      3.     DocumentRoot "/opt/local/www/mydomain.com/public"

      4.     ServerName mydomain.com

      5.     ServerAlias www.mydomain.com

      6.     ErrorLog "logs/mydomain.com-error_log"

      7.     CustomLog "logs/mydomain.com-access_log" common

      8.     <Directory "/opt/local/www/mydomain.com/public">

      9.         Options FollowSymLinks

      10.         AllowOverride None

      11.         Order allow,deny

      12.         Allow from all

      13.     </Directory>

      14. </VirtualHost>

      You can see where it sets what directory to go to, where it says to treat www.mydomain.com the same as mydomain.com, and then in the Directory block it sets permissions. The actual permissions instructions are pretty arcane. The most important thing to note is the line

      1. AllowOverride none
      This is not typical, but it's better, as long as you don't forget you did it.

      Here's the skinny: A lot of web apps like WordPress and Drupal need to set special rules about how certain requests are handled. They use a file called .htaccess to set those rules. By setting AllowOverride none you're telling Apache to ignore those files. Instead, you can put those rules right in the <Directory> blocks in your vhosts file. It saves Apache the trouble of searching for .htaccess files on every request, and it's a more difficult target for hackers. .htaccess is for people who don't control the server. You do control the server, so you can do better.

      1. If others will be putting sites on the server and you don't want them fiddling with the config files, you can allow .htaccess to override specific parameters. Read up in the Apache docs to learn more.
      2. If you are using SSL, you also need to set up a VirtualHost entry for port 443. That entry will also include the locations of the SSL certificates.
   3. Add further blocks that match the domains you will be hosting.
   4. Restart Apache and test your setup. http://127.0.0.1 should go to your default directory. Testing the domains is trickier if you don’t have any DNS entries set up for that server. I’ll write up a separate document about using /etc/hosts to create local domains for this sort of test.
4. MILESTONE - You have done it. A fully operational LAMP environment on your Mac, suitable for professional Web hosting.

(Optional) Install phpMyAdmin

phpMyAdmin makes some database operations much easier. There have been security issues in the past, so you might reconsider on a production machine, but on a development server it can be a real time saver.

1. 1. sudo port install phpMyAdmin
2. Update your Virtual Hosts with the domain you want to use to access phpMyAdmin, which is by default at /opt/local/www/phpmyadmin/
3. test - log in as root.
4. Configure - configuring phpMyAdmin fills me with a rage hotter than a thousand suns. It just never goes smoothly for me, whether I use their helper scripts or hand-roll it while poring over the docs. Maybe if I do it a few more times I’ll be ready to write a cookie-cutter guide for that, too. In the meantime, you’re better off getting advice on that one elsewhere.

Wrapping Up

I hope this guide was useful to you. I'm he kind of guy who learns by doing, and I've made plenty of mistakes in the past getting this stuff working. Funny thing is, when it goes smoothly, you wonder what the big deal was. Hopefully you're wondering that now.

If you find errors in this guide, please let me know. Things change and move, and I'd like this page to change and move with them.

Keep up to date: One of the big advantages of this install method is that updates to key software packages get to your server faster. Use that power. Run the update commands listed in step one regularly.

1. The script that tests the PHP-MySQL connection is based on one I found at http://www.pinoytux.com/linux/tip-testing-your-phpmysql-connection

Appendices

Appendix 1: A brief explanation of sudo

In the UNIX world, access to every little thing is carefully controlled. There's only one user who can change anything they want, and that user is named root.

When you log in on a Mac, you're not root, and good thing, too. But as an administrator, you can temporarily assume the root role. You do this by preceding your command with sudo. (That's an oversimplification, and you will have earned another Geek Point when you understand why. In the meantime, just go with it. sudo gives you power.)

When you use sudo, you type your password and if the system recognizes you as an administrator it will let you be root for that command.

For convenience, you only have to type your password every five minutes, but you do need to repeat 'sudo' for each command.

Just remember, as root you can really mess things up.

Jerry told me to edit the file, you lament, but he didn't say how. Kind of strange, considering the minute detail of the rest of the guide. The thing is, there's not one easy answer.

Let's start with the two kinds of text editors. There are editors like vim and pico that run right in terminal. They are powerful, really useful for editing files on a remote box, and if you know how to use them you're not reading this footnote. The other option is a windowed plain-text editor. TextEdit is NOT a plain-text editor. There are a lot of plain-text editors out there, and they all have their claims to fame. You can use any of them to edit these files.

Whoops! That brings us to the gotcha: permissions. In UNIX, who can change what is tightly controlled. Many of the files we need to edit are owned by root, the God of the Machine, so we need to get special permission to save our changes. Many of the plain-text editors out there will let you open the file, but when it comes time to save... they can't. You don't have permission.

Some editors handle this gracefully, however, and let you type your admin password and carry on. BBEdit and its (free) little brother TextWrangler give you a chance to type your password and save the file. I'm sure there are plenty of others that do as well.

BBEdit and TextWrangler also allow you to launch the editor from the command line, so where I say above edit ~/.profile, you can actually type edit ~/.profile and if you have TextWrangler installed, it will fire right up and you'll have taken care of the permissions issue. (If you decided to pay for BBEdit, the command is bbedit ~/.profile.) I'm sure there are plenty of other editors that do that too.

I'm really not endorsing BBEdit and TextWragler here; they just happen to be the tools I picked up first. Over time I have become comfortable with their (let's call them) quirks. Alas, finding your text editing answer is up to you. If you're starting down this path, it's only a matter of time before you pick up rudimentary vim or pico skills; eventually you'll be using your phone to tweak files while you're on the road. It's pretty empowering. But is now the time to start learning that stuff? Maybe not. It's your call.