BeigeJournal

I work in a laboratory. We just purchased a bottle of 1-methyl-2-pyrrolidone. The label says, “Irritant. Irritating to eyes and skin. In case of fire and/or explosion do not breathe fumes.” Indeed, I think we can all agree that in any fire and/or explosion you’d do best to avoid hanging around breathing the fumes.

Blosxom is small and simple, but like any software it won’t work at all if the required files are not in the proper places and the configuration variables are wrong. The existing documentation is a bit vague on just how to get the thing going, and it is very frustrating trying to debug something that won’t work at all. I’m here to help, with this guide to getting blosxom installed and at least minimally running. My installation was on a web hosting service using Unix. I’m an experienced Unix user and this document thus is written from the prospective of someone used to installing Unix software but new to blosxom.

blosxom.cgi goes in your cgi-bin directory, naturally. You’ll also have to create a blosxom data directory and plugin directory. You need to change the title and description in blosxom.cgi, naturally, but the harder part is the $datadir and $plugindir. Your hosting service likely did something clever with the web server’s document root and the FTP server configuration and it may be quite non-obvious what the real path to your new data rectory is. See the blosxom FAQ entry on this subject. You need to get this right or you’ll get nothing but the default header and footer with no postings. Put a test file or two in your data directory. The file format is simple, first line is the title, remaining lines are the body. Use the extension .txt.

Try it out by accessing a URL which will be of the general form http://www.yourhost.com/cgi-bin/blosxom.cgi, with your host and cgi directory. You ought to get your test entry(s) with the default blosxom wrapper.

The default output is somewhat ugly. If you get and unpack blosxom_flavor_sampler.zip, you’ll get some flavor files using the pre-theme system. There are separate files for content_type, head, story, and foot. There are several of each, for different flavors, distinguished by the extension. In blosxom.cgi “html” is the default flavor, and so the settings in the .html flavor files will be used. If you use the url http://yoururlhere/blosxom.cgi/index.1993 you’ll get the spare, minimalist 1993 style, if you use http://yoururlhere/blosxom.cgi/index.index you get the index style, and http://yoururlhere/blosxom.cgi/index.html is the same as the default http://yoururlhere/blosxom.cgi/index. You can also access a single entry with something of the form http://yoururlhere/blosxom.cgi/testentry.1993

There are a few flavors and themes available for download. For the themes you’ll need the theme plugin, which consolidates the required files and makes life easier. Install the theme plugin by setting $theme_dir and $theme_dir_url and put it in your plugin directory. Each theme gets its own subdirectory in the themes directory. Some of the themes can then be tried using the yoururl/blosxom.cgi/index.themename format, but Kozo Avo’s graffiti and iztsu have html, index, and rss variants, and the only way I know to get them to work is to set the $theme_dir as /your/path/here/themes/graffitti (or iztsu) rather than /your/path/here/themes, and use .html, .index, or .rss. Whatever you use will need at least a light editing to set your name and e-mail and favorite links in place of the examples.

You’ll need plugins. Writeback is probably high on your list. (Otherwise why bother with all this software?) You’ll need to set the writeback directory in the writeback plugin, and make sure that the web server will be able to write there. You may need to make it world-writable. The .writeback flavors that come with the package are good enough for testing. Koza Avo’s themes work well with writeback.

I highly recommend entries_index_tagged, which allows you to put the date of creation (or the date you want to use) in the file instead of relying on the file modification time stored by the filesystem. If you upload by FTP the filesystem time will be the time of upload, not the time you edited the file. Storing the time in the file is also much less likely to lead to trouble if you need to move to a different server or restore from backups since the filesystem modification time won’t matter. Follow the installation instructions on the entries_index_tagged web page. The Perl modules will need their own directory named Time in the Perl modules directory you created when you installed the modules plugin. Note that running perldoc on most of the plugins will show some documentation, or you can just examine the plugin file itself for documentation and comments. Once entries_index_tagged is running keep in mind that the dates are cached in .entries_index_tagged.index in your plugins state directory, so if you want to change the date you have to either delete that index file or remove/rename the blog entry, reload the directory through blosxom via your browser, then restore the entry, so a new line will be written in the .index.

If you install the find plugin, you need to create the log file (“queries” in the plugin state directory by default) and give it suitable permissions before it will work.

At this point your blog ought to be functioning and you will hopefully be familiar enough with installing plugins and themes to be able to continue tinkering.