Recently I had cause to set up a WordPress blog engine on a virtual host on bonzo. My experience follows:

First I need to set up DNS for the domain. The owner of the domain used the registrar’s control panel to set the authoritative nameservers to ns1.afraid.org through ns4.afraid.org, which are the nameservers provided by FreeDNS.

Next, I log into my FreeDNS account, add the new domain to my domains, and point the domain and www. to bonzo’s IP address. I don’t have mail setup yet, so I’ll ignore the MX record for now.

Now, querying the domain in a web browser should bring me to my site on bonzo…sure enough, it does.

The next step isto set up virtual hosting on bonzo, which I’ve not yet had a need to do. The Apache docs on virtual hosting refer to virtual hosting by host name ‘name-based virtual hosting’.

It’s pretty straightforward; you define what IP addresses and host names you want to associate with what server roots. There is one huge gotcha:

(From the name-based virtual hosting docs:)

Now when a request arrives, the server will first check if it is using an IP address that matches theNameVirtualHost. If it is, then it will look at each <VirtualHost> section with a matching IP address and try to find one where the ServerName or ServerAlias matches the requested hostname. If it finds one, then it uses the configuration for that server. If no matching virtual host is found, then the first listed virtual host that matches the IP address will be used.

As a consequence, the first listed virtual host is the default virtual host. The DocumentRoot from the main server will never be used when an IP address matches the NameVirtualHost directive. If you would like to have a special configuration for requests that do not match any particular virtual host, simply put that configuration in a <VirtualHost> container and list it first in the configuration file.

This is definitely not what I would expect. It means I have to make sure that the current server root is present as the first <VirtualHost> element, else my existing site will break.

So, first I’ll create the <VirtualHost> in /usr/local/etc/apache22/httpd.conf entry for my existing doc root and make sure that works:

# Apply virtual hosts to all requests
NameVirtualHost *:80

# The 'default' virtual host, used when the host doesn't match one of the others
<VirtualHost *:80>
    DocumentRoot /usr/local/www/drupal
</VirtualHost>

Next, an apachectl graceful to restart with the new config, and all is well. Requests to apocryph.org and bonzo.celatrix.com are still handled by my Drupal install as before.

Now I can create a separate doc root for the new domain, and point queries to it there. I’ll use /usr/local/www/craeton.com/:

bonzo# mkdir /usr/local/www/craeton.com
bonzo# chown www /usr/local/www/craeton.com/
bonzo# chgrp www /usr/local/www/craeton.com/

And another <VirtualHost> in httpd.conf accordingly:

<VirtualHost *:80>
    ServerName craeton.com
    ServerAlias *.craeton.com

    DocumentRoot /usr/local/www/craeton.com
</VirtualHost>

Then a <Directory> entry to define the behavior of the /usr/local/www/craeton.com directory when exposed by Apache:

# DocRoot for the craeton.com virtual host
<Directory "/usr/local/www/craeton.com">
    Options Indexes FollowSymLinks
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

I basically just copied the settings from the <Directory> entry for my default doc root.

So now, requests to craeton.com should resolve to this new folder. I’ll drop a simple index.html file and see what happens…it works.

Next I’ll need to create a MySQL database, user, and password for WordPress to use. First, the database:

$ mysqladmin -u root create wp_craeton -p
Enter password:
$

Now the user and password:

mysql -u root -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 16893 to server version: 5.0.9-beta

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> grant all privileges on wp_craeton.* to 'wp_craeton'@'localhost' identified by '[secret]';
Query OK, 0 rows affected (0.06 sec)

mysql> flush privileges;
Query OK, 0 rows affected (0.03 sec)

Too easy.

Now I’m ready to install WordPress into this folder. There’s a port in /usr/ports/www/wordpress, but PHP apps like WordPress are so easy to get running I’d rather grab the latest bits from wordpress.org so I have control over the install.

I’ll download the latest directly on bonzo via my trusty SSH session.

$ wget http://wordpress.org/latest.tar.gz
$ tar xzf latest.tar.gz
$ ls
index.html      latest.tar.gz   wordpress

So, it extracted into a ‘wordpress’ folder. I don’t want that; I want the WordPress stuff immediately under the creaton.com/ folder. Easy enough:

mv wordpress/* .

Looking at the readme.html included in the tarball, there is a ‘Famous Five-minute Install’:

1. Unzip the package in an empty directory
2. Open up wp-config-sample.php with a text editor like WordPad or similar and fill in your database connection details
3. Save the file as wp-config.php
4. Upload everything.
5. Open /wp-admin/install.php in your browser. This should setup the tables needed for your blog. If there is an error, double check your wp-config.php file, and try again. If it fails again, please go to the support forums with as much data as you can gather.
6. Note the password given to you.
7. The install script should then send you to the login page. Sign in with the username admin and the password generated during the installation. You can then click on ‘Profile’ to change the password.

Ok, item 1 is done. I’ll copy wp-config-sample.php to wp-config.php and put the DB connection info in it.

It was pretty easy; I just edited the DB info as it said:

<?php
// ** MySQL settings ** //
define('DB_NAME', 'wp_craeton');    // The name of the database
define('DB_USER', 'wp_craeton');     // Your MySQL username
define('DB_PASSWORD', '[secret]'); // ...and password
define('DB_HOST', 'localhost');    // 99% chance you won't need to change this value

// You can have multiple installations in one database if you give each a unique prefix
$table_prefix  = 'wp_';   // Only numbers, letters, and underscores please!

// Change this to localize WordPress.  A corresponding MO file for the
// chosen language must be installed to wp-includes/languages.
// For example, install de.mo to wp-includes/languages and set WPLANG to 'de'
// to enable German language support.
define ('WPLANG', '');

/* That's all, stop editing! Happy blogging. */

define('ABSPATH', dirname(__FILE__).'/');
require_once(ABSPATH.'wp-settings.php');
?>

Step 3 is equivalent to the copy to wp-config.php and thus doesn’t apply.

Step 4 is not applicable either, since I’m doing all this directly on bonzo via SSH.

In step 5, I navigate to the craeton.com/wp-admin/install.php. I get a splash screen and a ‘First Step’ link, which I click.

The first step in this install process prompts for a blog title and an email address. I’ll provide it and move on.

In the next screen it pauses to create the database tables, then generates a temporary password for the admin user. I’m admonished to not forget it, and given a link to the login page. I’ll go there now.

Logging in w/ the admin account and random password, I get a clean, simple admin GUI. I’ll change the password to something memorable, and declare victory. Too easy!