Archive for the 'guides' Category

WordPress OS X Install Tips

Saturday, September 16th, 2006

I like having WordPress running on my laptop because it makes it so easy to experiment with site changes without breaking the actual web site. Its not terribly difficult but there are a couple of quirks that required some googling to discover. Here is my recipe for installing WordPress on Mac OS X. No guarantees but at least its a starting point until things change again.

I’m assuming you are starting with a vanilla (non-Server) Mac OS X install, Mac OS X 10.4.6 in this particular case. The core steps needed are: installing MySQL, enable PHP in the built-in Apache web server and finally installing and configuring WordPress. I’m using a dedicated non-admin account but the same procedure should also work for the main site if you change the root web folder references to /Library/WebServer/Documents.

I’m also assuming you can handle downloading and installing apps and know the basics of using a Terminal command line and some command line editor such as vi or pico.

NOTE: I’m using WordPress here but the basic procedure is similar for other web content apps such as Drupal.

STEP 1 – Installing and Configuring MySQL Database Support

  1. Visit http://mysql.org/downloads/mysql and download the appropriate Standard installer package for your machine. Make sure you choose the appropriate architecture for your machine (PowerPC for G3/G4, PowerPC 64 bit for G5, or Intel.) The Mac section is about 3/4 of the way down the page. Use the current stable version which is 5.0 at the time I write this.
  2. Install the main MySQL package, drag the preference pane to /Library/PreferencePanes and optionally install the StartupItem if you want MySQL launched at boot (not required as you can manually start/stop it from the preference pane as needed.
  3. Start MySQL via the new preference pane in System Preferences. You’ll need admin authorization.
  4. To avoid having to type long strange paths in command lines use your favorite command line editor to add the folder with the MySQL binaries to your shell’s search path. If you’re using the default bash shell that means adding this line to the bottom of the .profile file in your home folder (create it if it doesn’t exist):
    export PATH="$PATH:/usr/local/mysql/bin"

The default MySQL setup has several unnecessary anonymous accounts and does not have a password on the root account (these are all internal to MySQL and have nothing to do with regular Mac OS X accounts.) We’re going to correct those issues as well as delete a test database.

  1. Issue these commands from a Terminal session (you type what’s after the $ or > prompt. Substitute your chosen MySQL rot password for {ROOTPASS} and the Bonjour computer name (shown at the top of Sharing in System Preferences) for {HOST}
    $ mysql -u root
    > drop database test;
    > delete from mysql.user where User = '';
    > flush privileges;
    > set password for root@localhost = password('{ROOTPASS}');
    > set password for root@127.0.0.1 = password('{ROOTPASS}');
    > set password for 'root'@'{HOST}.local' = password('{ROOTPASS}');
    > quit

OK, MySQL is ready to roll. If you want it launched automatically every time you boot your machine you have to install the StartupItem and also turn on the appropriate checkbox in the MySQL system preference pane.

STEP 2 – Create the WordPress MySQL Database and User

WordPress doesn’t create its own database so we have to do that ourselves. We’re also going to create a dedicated MySQL user account for WordPress. This isn’t strictly necessary, you can use the root account, but its good security policy for the final web site and not hard to do. I’m using a database name of ‘wordpress’, a MySQL username of ‘wpuser’ and a password for that username of ‘wppass’. Feel free to substitute your own choices.

QUIRK #1: MySQL v4.1 made changes to its password format that WordPress or probably more accurately PHP does not handle but fortunately they included a function old_password() to generate the older format that works.

  1. Perform the following commands from a Terminal command line:
    $ mysql -u root -p
    Enter Password: {ROOTPASS}
    > create database wordpress;
    > grant all privileges on wordpress.* to wpuser@localhost identified by 'foo';
    > set password for wpuser@localhost = old_password('wppass');
    > quit

STEP 3 – Activate PHP in the Apache Web Server

WordPress is written in PHP which is not enabled by default in the built-in Apache web server used for Personal Web Sharing on Mac OS X. To fix that you must un-comment two lines in the Apache configuration file and start (or restart) the server. The configuration file requires root access to edit so you’ll need to invoke your favorite command line text editor, vi in my case, via ‘sudo':

  1. $ sudo vi /etc/httpd/httpd.conf
    Search for the following two lines, delete the leading # from each then save the changes:
    #LoadModule php4_module libexec/httpd/libphp4.so
    #AddModule mod_php4.c
  2. Open the Sharing preference pane in System Preferences and in the Services tab turn ON Personal Web Sharing. If it was already turned ON then turn it OFF then back ON to make sure the configuration changes take effect.

STEP 4 – Install WordPress

I wanted to install WordPress in a Mac OS X user account set aside specifically for that purpose which means WordPress should go into the Sites folder of that account’s home folder. The WordPress site can then be accessed with the URL http://localhost/~{USER} where {USER} is the short name for the dedicated account. Alternatively, you can install it in the main web server root folder at /Library/WebServer/Documents and access it at http://localhost/. Your call.

  1. Throw out the existing default web page items from the Sites folder if you haven’t already done so.
  2. Download the latest version of WordPress from http://wordpress.org/latest.zip and extract the archive’s contents if Safari hasn’t already. You should wind up with a folder named simply wordpress.
  3. Copy the contents of the downloaded wordpress folder into the Sites folder. Don’t drag the entire folder, you just want its contents.
  4. In the Sites folder, duplicate the document named wp-config-sample.php and rename it to wp-config.php. Open wp-config.php with your favorite plain text editor then edit the first three MySQL settings to read as follows (substitute your MySQL wordpress username and password if necessary):
    define('DB_NAME', 'wordpress'); // The name of the database
    define('DB_USER', 'wpuser'); // Your MySQL username
    define('DB_PASSWORD', 'wppass'); // ...and password

QUIRK #2: Starting in Mac OS X 10.4.4 Apple changed the location where PHP expects to find a crucial MySQL file and the result is that WordPress can’t connect to its database. You scratch your head, verify that you entered the database settings correctly and become thoroughly confused. Fortunately there is a very easy fix that we can incorporate directly into the WordPress settings file, no changes to Mac OS X are needed at all (I discovered it in the comments to a post that proposed a different solution. crimemon, whoever you are, you are my hero!)

  1. For Mac OS X 10.4.4 and later only! change the MySQL settings line after the three above to read:
    define('DB_HOST', 'localhost:/tmp/mysql.sock'); // 99% chance you won't need to change this value

Looks like we’re in that unfortunate 1%.

STEP 5 – Configure WordPress!

The first time you access WordPress it has to install its database tables and perform other one-time setup. The first wordpress user created will be the admin user and is assigned a random password. Your first action should be to login as the admin user and change that password to something you can remember. If this site were visible to the outside world you’d need to choose a secure password to keep boneheads from guessing it and screwing around with your site and its settings. If it will only be used to experiment with WordPress locally its less of an issue but it might be a good idea to do so anyway to reinforce good habits.

Substitute the short name of the Mac OS X account where WordPress is to be installed for {USER}.

  1. Point your web browser at http://localhost/~{USER}/wp-admin/install.php or http://localhost/wp-admin/install.php if you used the main web server root folder for your install. If you’ve done everything correctly and no quirks have been added or changed since I wrote this, you should be greeted by a screen telling you that WordPress has to be set up with a link to STEP 1 in the process. Click the link but don’t go anywhere because its basically instantaneous. If instead of the setup screen you are told that WordPress can’t connect to its database then double check that you’ve entered the correct database settings in wp-config.php. If that still doesn’t help then get googling! Search for database issues in WordPress with whatever version of Mac OS X you are using.
  2. You will be given the name of the admin account (admin), the initial random password assigned to it and a link to login to WordPress. Click the link, login as admin, then immediately edit your profile to assign a password you can remember.

Fin

And that’s it! You now have a functional WordPress install and that’s as far as I’m taking you with this post. The official WordPress site has lots of resources and extensive documentation so that’s probably a good place to start.

Issues

If you try the alternate perma-link formats you’ll discover they don’t work with the above setup, the reason being that Mac OS X does not support using .htaccess files with Apache in its default configuration, and that is essential for perma-links and other plug-ins that need URL rewrite rules to do their thing. Its easy to enable .htaccess for the root folder but the hints I’ve found for enabling them in individual Mac OS X account Sites folders don’t seem to work. I’ll post additional instructions if and when I figure that out.