A weblog about Ode (ode-is-simple.com)

You may prefer to read this post using the 'text_page' theme, a single column layout without the sidebar.

I'm posting a short version of the installation instructions included with the release for a couple of reasons:

1. I've been told the instructions included with the release are too long.
2. I think it's important to give anyone thinking about installing Ode a little preview of what the process is like (before downloading the release).

I should also mention that the requirements are minimal - An Apache-like web server with support for Perl. Ode itself, requires no non-standard modules (though various addins might).

The release package includes very thorough installation instructions. They're so detailed in fact that I've been told they actually confuse; making installation seem more complicated than it is. How's that possible?

Well, if I were to guess... When faced with a lot of reading we all tend to skim. That may be a good strategy for reading a long newspaper or magazine article, an academic paper, or a book, but it's not a good way to deal with what are essentially step-by-step instructions.

For example

Instructions for baking cookies

1. Preheat oven to 400 degrees.
2. Place cookies in oven for 15 minutes.
3. After 5 minutes reduce heat to 325 degrees.
4. Take cookies out of oven.
5. Let cool before eating.

If you miss even one of those steps, the process will most likely not end with you enjoying delicious cookies.

Of course, it would be difficult to miss one of those steps as written. But if I stretched that out to be 5 pages of running commentary, then you might miss something. And if you did, it wouldn't be your fault.

So, what to do? There are two options:

Slow down and read through the longer version of the instructions included with the release, making a special effort not to miss anything.

Read the shorter version of the installation instructions here.

Either way, be sure to ask if you have questions or run into any difficulty.

I have absolutely no doubt that we can get Ode up running for you. (Assuming the host computer meets the necessary requirements.)

Remember, Ode is intended to be instructional. With that in mind, I'll repeat something I've heard over and over again in school:

1. The only stupid question is the one you don't ask.
2. Others are likely to have the same question. By asking you're not just benefiting yourself.

I like to think that Ode is equal parts project and community. Asking questions is a large part of what makes a community effort like this work.

Install Instructions: The Short Version (r1_2_3)

Part 1: Copy files to your server

Step 0: Download the latest release

http://ode-is-simple.com/downloads/ode_releases/ode_current.zip

Unzip the archive

The result will be a single folder titled ode_r1_x_x. (Where 1_x_x is the current version number.)

Step 1: Copy the script to the server

Ode itself is a single Perl cgi file titled 'ode.cgi'. You'll find this file in the Part1 folder:

ode_r1_2_3/
  Part1/
    ode.cgi

Ignore the other files in that directory and copy just 'ode.cgi' to wherever cgi files belong on your server.

Step 2: Copy the 'data' folder to the server

This folder includes Ode's config file and the 'addins' folder. This is the folder where addins are kept. What's an 'addin'.

As you may know, Ode is extensible, which is to say it's possible to write little self-contained extensions, referred to as 'addins' under Ode, that extend or modify what Ode is capable of doing on its own.

(The release package includes just two addins. Others are available now. More are being written right now. Still more are planned.)

You'll want to copy the data folder and it's contents to a location which IS NOT under your web servers document root.

ode_r1_2_3/
  Part2/
    data/

Step 3: Copy The 'ode_site' folder to your webserver

The ode_site folder contains some sample posts and themes for your site.

This folder will serve as Ode's document root. That means that must be copied to a location under the webserver's document root.

ode_r1_2_3/
  Part3/
    ode_site/

Again, you'll want to copy the ode_site folder and it's contents to a location which IS under your web servers document root.

That's it for the actual installation.

Now we need to config Ode so that it can find all of those files you just copied to the server.

Part 2: Configuration

Step 4: Tell ode.cgi where to find the configuration file

Open the file 'ode.cgi'

Scroll down until you find the section labeled CONFIGURATION SECTION.

Within the config section locate the line

$config_dir_f = '';

You need to specify the path to the directory containing the configuration file. The config file is inside the data directory you copied to the server earlier.

The value you want here is the absolute path to the data directory.

After you add the path that line should look something like:

$config_dir_f = '/Library/WebServer/Data/ode/';

Note that I've typed the absolute path inside the single quote marks.

Save the changes and close ode.cgi.

That's the only change you'll ever need to make to ode.cgi. (All other configuration is handled in the config file.)

Step 4: Edit the config file

Open the configuration file in a text editor.

The file is titled 'ode_config' and is located directly under the data directory.

data/
  ode_config

Scroll down until you see the config section.

We're only going to be changing 3 of the settings. The other settings are optional and do not need to be modified to get the script running. (You'll find a complete description of each of the settings in the config file itself.)

These three are:

Site document root (*$document_root*) Addins directory (*$addin_dir*) Document root URL (*$document_root_url*)

Step 4.1: Set the path to the Site document root

Site document root is the absolute path to Ode's document directory. This is the ode_site folder you copied to the server earlier.

Find the line

$document_root = '';

And type the path to the ode_site folder inside the single quote marks, like so:

$document_root = '/Library/WebServer/Documents/ode_site';

Step 4.2: Set the path to the Addins directory

The Addins directory is inside the data directory you copied to the server earlier. This is similar to the same path you set in ode.cgi earlier except that it ends with the name of the addins directory itself.

The line you're editing is:

$addin_dir = '';

Type the path to the addins folder inside the single quote marks, like so:

$addin_dir = '/Library/WebServer/Data/addins/';

Step 4.3: Document root URL

This is the URL that corresponds to the ode_site directory you copied to the server earlier.

For example, let's say that I have a webserver at the domain:

http://sample.net

If I placed the ode_site folder at my webserver's document root, then the URL to the ode_site directory would be:

http://sample.net/ode_site

This is the value I'd use for $document_root_url.

The line you're editing is:

$document_root_url = '';

Type the document root url between the single quote marks, like:

$document_root_url = 'http://sample.net/ode_site';

Save the changes you just made and close the ode_config file.

You're done.

Step 5: Make sure it works

Type the address to the ode.cgi file into your browser's address field.

For example, if I placed ode.cgi in my servers cgi-bin directory, the corresponding URL would be:

http://sample.net/cgi-bin/ode.cgi

How do you can you tell if it's working?

If you see what looks like a typical HTML page, complete with a theme, and content from the sample posts included in the ode_site directory, and if there are no errors, then it's working.

At this point you have a fully functioning Ode installation.

If you run into problems, ask for help on the forum (forum.ode-is-simple.com)

To answer a question you may have, yes it is possible to hide the cgi in that address so that the address of your site looks like one of following:

http://sample.net/weblog http://sample.net/

That's a separate issue, i.e. not actually part of the installation.

The documentation included with the release is more detailed, and may help if this didn't provide you with the information you need. Of course you can always ask for assistance.

Try posting to the forum, or email me directly at rob[at]ode-is-simple.com.