What You Need

1. A computer. I'm doing this on OS X 10.4.2. Your mileage may vary.
2. A pre-configured Apache install. You need to know where the paths are for everything, and what user apache runs as. For this tutorial, we're going to be using the OS X standard /Library/WebServer/Documents as the DocumentRoot, and /Library/WebServer/CGI-Executables for the appropriate ScriptAlias. Please replace where necessary with your own particular paths. You'll also need to have permissions to write to these directories - su to root if you have to for these terminal commands.
3. Perl. If you're on OS X or Linux, this shouldn't be an issue.
4. Basic knowledge of HTML, for template editing.

How To Do It

Setup And Install

Let's set up some directories we're going to need.

mkdir /Library/WebServer/Data
mkdir /Library/WebServer/Data/Blosxom
mkdir /Library/WebServer/Data/Blosxom/plugins
mkdir /Library/WebServer/Data/Blosxom/plugins/state
mkdir /Library/WebServer/Documents/Blosxom/

This sets up your plugin directory (/Library/WebServer/Data/Blosxom/plugins) and a Blosxom data directory (/Library/WebServer/Documents/Blosxom/). I'll be referring to these paths by these names in the future, so keep track. We need to make sure that the plugin state directory can be written by the web user, so let's change the owner to what Apache runs as:

chown www /Library/WebServer/Data/Blosxom/plugins/state

Now, let's download some flavour files - essentially templates - for Blosxom and toss them in our data directory.

cd /Library/WebServer/Documents/Blosxom/
curl -O http://www.blosxom.com/downloads/blosxom_flavour_sampler.zip
unzip blosxom_flavour_sampler.zip 
mv flavours/* ./
rm blosxom_flavour_sampler.zip
rm -rf flavours

You should now have four templates across three flavors in your directory: index, html, and 1993 (which looks like a web page in 1993). This will be more than enough to get us started.

Now, let's actually install Blosxom.

cd /Library/WebServer/CGI-Executables/
curl -O http://www.blosxom.com/downloads/blosxom.zip
unzip blosxom.zip
rm blosxom.zip

That is literally it. Assuming Apache is running, you should be able to now go to http://yourserverhere/cgi-bin/blosxom.cgi and see the install running. (If not, you'll need to drop this tutorial and check your Apache config, probably by scouring the error_log.)

Configure

The default version is configured in a fairly mundane way, so let's configure it slightly before we start posting to it. Open up blosxom.cgi in your favorite text editor:

nano blosxom.cgi

Variables you should replace (with helpful suggestions denoted below) include:

$blog_title = "My Workblog";

Replace this with a nice, proper title for your workblog. Names of songs from your favorite video game or Chinese proverbs are highly recommended.

$blog_description = "My workblog.  Isn't it neat?";

This goes in the RSS feed and the templates; make your own by-line! You might want to include a disclaimer about the privacy of the information.

$datadir = "/Library/WebServer/Documents/Blosxom";

If you aren't running on OS X, you will likely have to change this to the appropriate path.

$num_entries = 20;

The default of 40 is overkill. I recommend 20.

$plugin_dir = "/Library/WebServer/Data/Blosxom/plugins";

This you will absolutely need to set, as there's no default. We'll be installing plugins soon, so be sure to do this.

Your First Post

Now that all that is done, so we're ready to make our first post! Jump back into the data directory and start carving yourself a category path; anything structure you want is possible. I use something resembling this:

maintenance/ (patch notes, diagnostics)
projects/
    (one folders for each project, with subfolders if necessary)
schedules/ (todos, etc)
tools/
    (one subfolder for each piece of software)
vendors/
    (one subfolder for each vendor, for issue tracking)

For those of you in the Church of GTD, here's a sample I whipped up based on the traditional workflow diagram.

@inbox/
action/
    planning/
    delegate/
        waiting/
    defer/
        next/
        thisweek/
        thismonth/
done/
no-action/
    reference/
    someday/
    trash/

Tangent: The wonderful thing about Blosxom for GTD is that you can literally toss these tasks between folders without having to wait for rebuilding or what have you. You can bookmark the individual folders (@inbox and action/defer/next) and just view what you need to get done. And with Quicksilver in hand, you can blast this stuff around, append text to existing entries, and so on. All this, and it takes up far less space than 43 (physical) folders. Even if you're not going to follow the book, these features will shine through for organizing your work.

Failing your interest in these, let's just make an easy one for now:

mkdir /Library/WebServer/Documents/Blosxom/projects
mkdir /Library/WebServer/Documents/Blosxom/projects/workblog

And now, let's open our first post. All posts should be .txt files; the first line contains the title, and the rest should be the HTML body. Here's a test post for the lazy

My First Blosxom Post

<p>Blosxom is really awesome, look how quickly I'm blogging!  Wheeeeee!  Thanks <a href="http://vjarmy.com/">Dan</a> for the great tutorial!</p>

Save this as /Library/WebServer/Documents/Blosxom/projects/workblog/firstpost.txt, reload your blog, and BLAMMO, there's the post - with a category and a perm link. It gives you a warm, fuzzy feeling, doesn't it?

Customizing Templates & Plugins

By now, you've probably noticed Rael's initial flavours are a little superfluous, so let's figure out how to edit it. If you open /Library/WebServer/Documents/Blosxom/head.html, you'll find you can remove the cruft - I recommend pulling the "Flavours" and "Links" sections. You could also change the text to the RSS section, and tweak the CSS if you don't like that blue sidebar.

A quick explanation of flavour files might be useful at this point, so here's a tangent: each flavour consists of a handful of files, including a head, a story, a foot, and a content_type. All the files for a particular flavour end with the same extension (.html being the most standard one). Pages are constructed with head-story-foot, while content_type is used for MIME types. Edit the flavour files as needed, or you can roll your own.

We're nearing the home stretch - let's try some plugins. I've been raving about Markdown for a while; it'll let you write in a more natural way than straight HTML. Installation for this is easy:

cd /Library/WebServer/Data/Blosxom/plugins
curl -O http://daringfireball.net/projects/downloads/Markdown_1.0.1.zip
unzip Markdown_1.0.1.zip
mv Markdown_1.0.1/Markdown.pl ./Markdown
rm -rf Markdown_1.0.1*

Now go back to that test post and add this on a blank line:

# Markdown is awesome!

Save, and if your plugins folder is configured correctly, you can reload and notice a huge H1-styled line proclaiming the house-rocking nature of Blosxom.

Let's do one more plugin, which also involves a template tweak: the categorytree plugin.

cd /Library/WebServer/Data/Blosxom/plugins
curl -O http://fletcher.freeshell.org/downloads/find

Now go back into your head.html flavour template and add this somewhere in the big table on the left side:

<p>
<b>Search</b> <br />
$find::searchform   
</p>

Reload, and bam - search. You now have an easily searchable workblog. The search functionality can be configured a bit, so be sure to come back later and tweak the find file to your heart's delight.

Locking It Down

The last critical step in any workblog is to lock it down. I'm not going to go into doing simple htpasswd authentication or mod_auth_ldap installation and configuration for a few reasons: they're well documented, they'd take a long time to explain, and most people want to be bothered by the least number of logins possible. What I will instead suggest is the very secure Apache IP space restrictions, which will allow you to limit the site to your subnet. So pull up your httpd.conf file:

sudo nano /etc/httpd/httpd.conf

And add this section wherever you see fit:

<Directory "/Library/WebServer/CGI-Executables">
   AllowOverride None
   Order allow,deny
   Allow from 10.0.5
   Allow from 192.168.0.4
</Directory>

What this is doing is saying that for the CGI directory, Apache should process all the allow rules first, and should the user fail to meet them, deny the request. (Blocking the entire CGI directory is overly simplistic but I'm not big on the subtlety.) Apache, nicely enough, lets you put partial IP addresses in and it will wildcard the rest - no need to muck about with a subnet calculator (although it will take those as well, should you be more versed in that.)

Once you've allowed your IP spaces, do the usual Apache routine:

sudo apachectl configtest
sudo apachectl graceful

And like magic, you'll have an IP space restricted dark blog.

Moving Forward

This is the end of the road for our tutorial - there's plenty more to explore, though. Mostly I recommend checking out the Blosxom plugin directory and installing ones that interest you; I'd also recommend taking the time to play with the flavor files and getting something you won't mind looking at a lot.

Most of all, use it! Any time you get an email or link or whatever else you need to not forget about, dump it in a text file and stick it in one of your category folders. Categorize all your important info by project, so it's easily cross-referenced and accessible by others. Become familiar with Markdown syntax, as it will speed up your posting time considerably. Tell your co-workers, reference it in your emails - it's much easier to revise your documents and project plans locally rather than emailing the same people with slight document revisions over and over again.

---

Special thanks to Rael Dornfest and everyone involved in Blosxom for writing a fantastic tool, Suw Charman for getting me to be slightly more serious about the whole thing, and Richard Hu for reviewing this tutorial. If you enjoyed this tutorial, leave me a comment or trackback, bookmark it on del.icio.us, or drop me an email at user name "remydwd" at google's email service.