If I’ve learned anything over the last six months, it’s that having a personal space to stash all your notes and categorize your project space is something I can no longer work without. Yes, I know I’ve been [prattling on](https://vjarmy.com/archives/2005/06/workblogging_my.php) about the benefits of having your own workblog or darkblog (or whatever you’d like to call it); now it’s time to spread the love.
If you’re the sort of person who can’t manage their paper stack, the kind of worker who finds themselves scrambling from notebook to notebook looking for documents from a year ago, or are part of the tough crowd of people who like to Get Things Done, this 10 minute tutorial is for you.
# 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](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="https://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](https://vjarmy.com/archives/2005/06/take_note.php) about [Markdown](http://daringfireball.net/projects/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.
## 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](http://httpd.apache.org/docs/howto/auth.html) or [`mod_auth_ldap` installation and configuration](http://www.muquit.com/muquit/software/mod_auth_ldap/mod_auth_ldap.html) 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](http://www.blosxom.com/plugins/) 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](http://daringfireball.net/projects/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*