Installing Ikonboard 3.0.2

—by David O’Donnell, atropos@afp548.com

If you’re like many Web site managers, you’d like to add a little computer-mediated community to your site and bring in some additional eyeballs (and cash!). A number of community software packages are available that cost anywhere from USD 80.00 on up. Ikonboard (from Jarvis Entertainment Group, Inc.) is available for free, though for USD 250.00 you can purchase a license that will permit you to remove Jarvis' copyright information.

Ikonboard is a fairy capable package, from the little experimenting I’ve done. You can see the board in action by going to http://www.afp548.com/afpcgi/webboard/ikonboard.cgi.

Jarvis supplies installation instructions for Ikonboard, but they suffer from the flaw of being designed for people limited to FTP access. The board’s source archive is distributed as a Windows-centric “zip” file that confounds many decompressing tools. The following directions will help you set up a basic Ikonboard system.

Obtain Ikonboard Source
First, make sure you have a directory where you store incoming Unix source archives. I like to call mine “src” (original!) and put it in my home directory. We’ll refer to this directory as “$SOURCE".

Now, go to Jarvis' site (http://www.ikonboard.com/) and click on the “Download, Support and Member Center” link in the toolbar:

You can choose to register with the Ikonboard community, which will give you access to their feedback and support fora, or you can choose to skip that step and just get the package. I recommend registering—it’s free, and you never know when technical support will be needed. Once you register and log in, click on the Download link under Member Center Navigation. Click the “Ikonboard 3.0.2 [recommended]” link, agree to the license, and click the Download Now... link. Save the archive in $SOURCE.

Update CPAN modules and obtain mod_gzip
Launch Terminal and get into the CPAN environment by issuing the sudo perl -MCPAN -e shell command. (See Darian Lewis' tutorial and introduction to CPAN for more information on using CPAN.)

Ikonboard requires the CG1 and DB_File Perl modules be installed, so use the commands

install CG1 install DB_File

to obtain and install them. I installed CG1 version 2.80 and DB_File version 1.73 from CPAN.

You can save some space and configure Ikonboard to be able to reac gzipped archives. To do so, assume superuser rights and change to the /usr/sbin/ directory. Retrieve mod_gzip.c with the command

curl -O http://www.ehyperspace.com/mod_gzip/src/1.3.19.1a/mod_gzip.c

and install it as a priveleged comand with

/usr/sbin/apxs -i -a -c mod_gzip.c

Install Ikonboard source files
Now we’ll install the source files for Ikonboard. Jarvis distributes Ikonboard as a Windows ZIP file, which is rather annoying to the rest of us who don’t use Windows. If you downloaded the ib302.zip file from the console, StuffIt Expander should have expanded the contents out into a folder:

Unfortunately, StuffIt expander doesn’t perform line-end translation in text files when it expands files, so erase that folder and switch to your Terminal session. Navigate to $SOURCE and use the command unzip -a ib302.zip to expand it. Note, however, that unzip does not always seem to deal with tape archive (tar) files within ZIP files, so you may have to revisit this step and use another tool (like StuffIt Expander) to extract the tar files.. This behaviour is new with the ib302.zip file, and with luck will go away with their next release.

Change to the $SOURCE/ib302/ directory.

Now, change to the location on your Server where you want to put Ikonboard. If you only run one Web site on your Server, you can put it under the /Library/WebServer/CGI-Executables/ directory (or wherever you’ve set your DocumentRoot to be in Apache’s httpd.conf file). If you run multiple Web sites, and want them to have distinct instances of Ikonboard (which may be useful, since it is the only way to brand Ikonboard separately) then you’ll want to repeat the steps in this section for each Web site, and store copies of the sources in each site’s cgi-bin directory. Create a directory where Ikonboard’s files will go, such as “webboard/". We’ll refer to this place from here on in as $WEBBOARD. Change to $WEBBOARD.

Create the following directories (case is important):

• BACK_UP
• Data
• Database
• INCOMING
• INSTALL_DATA
• install_modules
• Languages
• OUTGOING
• Skin
• Sources

Use the command chomd 777 * to set the permissions on all of the directories you just created.

Change to $SOURCE/ib302/iB3_UPLOAD/cgi-bin/ and execute the following commands (remember to replace the full path to $WEBBOARD!):

cp -R INSTALL_DATA/* $WEBBOARD/INSTALL_DATA 
chmod 777 $WEBBOARD/INSTALL_DATA/* 
cp -R install_modules/* $WEBBOARD/install_modules 
chmod 777 $WEBBOARD/install_modules/* 
cp Data.tar Database.tar Languages.tar non-cgi.tar Skin.tar Sources.tar $WEBBOARD 
cd $WEBBOARD 
chmod 777 *.tar 
cd - 
cp ikonboard.cgi ikonboard.conf installer.cgi $WEBBOARD 
cd - 
chmod 755 *.cgi 
chmod 777 ikonboard.conf 
cd $WEBBOARD/.. 
chown -R www $WEBBOARD

Now, we need to change to where you’ll have Ikonboard 'appear' in your Site. If your Server only runs one Web site, that location will most likely be /Library/WebServer/Documents/; if you run multiple sites on your Server, you will probably want to put Ikonboard at the root of each site where it will be installed.

Execute the following commands:

mkdir iB_html 
chmod 777 iB_html 
cd iB_html 
mkdir uploads non_cgi 
chmod 777 uploads non_cgi 
cd ../.. 
chown -R www iB_html/

Configure Ikonboard
If your Server runs multiple sites, you will need to create a ServerAlias directive in your /etc/httpd/httpd.conf file to give the $WEBBOARD location a unique name. For AFP548.com’s installation, we added the following line:

ScriptAlias /afpcgi/ /Volumes/Storage/Web/AFP548.com/cgi-bin/

Launch your favorite browser and point it at $YOURSITE/$IBDIRECTORY/installer.cgi. Replace $YOURSITE with the URL to the site where Ikonboard will run, such as “http://www.yoursite.org/"; replace $IBDIRECTORY with the last directory component of $WEBBOARD, such as “webboard"; if you had to add a special ServerAlias directive, it should be prefixed to $IBDIRECTORY. For AFP548.com, for example, the URL was http://www.afp548.com/afpcgi/webboard/installer.cgi.

Click the “Proceed with the installation” link.

Now you need to configure the path information for Ikonboard. The installer makes a few guesses as to where things should go, but the guesses will almost certainly not be correct:

Your CGI Path should be replaced with $WEBBOARD. For single-site Servers, that will most likely be /Library/WebServer/CGI-Executables/webboard; for AFP548.com, it is /Volumes/Storage/Web/AFP548.com/cgi-bin/webboard.

Your NON-CGI Path should be replaced with the full path to the iB_html/ directory. For single-site Servers, that will most likely be /Library/WebServer/Documents/iB_html; for AFP548.com, it is /Volumes/Storage/Web/AFP548.com/iB_html.

Your CGI URL is the base portion of the URL to where Ikonboard will live. The installer will probably get this right, as it did for AFP548.com.

Your NON-CGI URL is the URL to the iB_html directory. For single-site Servers, it will likely be http://$YOURSITE/iB_html; for AFP548.com, it is http://www.afp548.com/iB_html.

Set the incoming and outgoing e-mail addresses to whomever will be administering Ikonboard (which may be different from whomever manages the board!); leave the email program set to “Send mail (Good for *NIX)” and its path to /usr/sbin/sendmail. If your Server runs outgoing mail service, leave the SMTP server line as it; otherwise, change it to your outgoing server.

Edit the “Website Name,” “Board Name,” “Board Description,” and “Website URL” as necessary, and click the “PROCEED >>” button.

Correct any errors that appear on the next page, then click “PROCEED >>".

Go ahead and let Ikonboard extract the tape archives for you, by clicking “PROCEED >>".

Check to make sure there are no errors in the Ikonboard file structures and click “PROCEED >>".

Ikonboard supports using MySQL as the database for its material, but this article does not cover that installation process. Accept the default DBM Database for now, and click “PROCEED >>".

The database is set up, so you can click “PROCEED >>". Let Ikonboard create its templates, and click “PROCEED >>"; click “PROCEED >>” again once database population is complete.

Create your Database Administrator account. This account will be like your Server’s root account, in that it will have complete control over the Ikonboard installation. Click “PROCEED >>".

Log in as Administrator and Start Tweaking!
Before you click on the final “PROCEED >>” button, on the screen announcing the completion of your Ikonboard installation, switch back to the Terminal. Change to $WEBBOARD, and rename installer.cgi to something else. Ikonboard will scream bloody murder if it sees installer.cgi when it tries to launch the board in your browser. Click the final “PROCEED >>” button.

You should see your new board, waiting for you to log in as Administrator and start setting things up! Much of Ikonboard’s configuration details are self-explanatory, but for those that aren't, check out Jarvis' extensive community site.