Although experienced Perl users will still need to read this page, installing Symbio should be a breeze for them; however, this explanation should also cover about anything newbies need to know to install Symbio properly.
Extract the archive you downloaded to a new directory on your hard drive. Windows users can do this using just about any archiver, e.g. WinRAR. For any other platform (and Windows as well, actually), the tar utility, in combination with gzip is probably available if you can't find the right tool. If you decide to use tar, but you're not familiar with it, just go:
tar Cxzf some_directory symbio-version.tar.gz
Obviously, you replace some_directory with the directory where to extract the files, and version with the version of Symbio you downloaded.
Find out where Perl is located on your server. Your host (or the appropriate support pages) will be able to tell you. Typically, the path to Perl is either /usr/bin/perl or /usr/local/bin/perl. Symbio's default is the former. If it differs from that value, open the files listed below this paragraph, which are all located in script-directory, and change the first line of those to #! (this is called the "shebang"), directly followed by the correct Perl path.
Choose a password for the configuration panel, open the file
password.pl in the config directory, located in
script-directory, and enter the password in that file, e.g.
Now we're going to upload the scripts to your webspace. You'll need two main directories:
The script directory: This directory will contain all the script and comment data files. Make sure it allows the execution of scripts inside it.
The resource directory: This directory will contain the files that are publicly available without parsing through Perl, i.e. images and stylesheets. Make sure the server doesn't try to run Perl for every file inside it, regardless of its extension.
After you've made your choice, open the file config/setup.txt, again in script-directory, and enter the full URL (i.e. what you would type in the location bar of your browser) to the resource URL after resourceurl=. Do not include the trailing forward slash. You can do the same for the script URL, but you may also set that one later on, once you've logged into your Symbio Control Panel.
The separation of the two directories is necessary because some servers have a strict configuration, which will assume every file inside the cgi-bin (although this name can differ) directory is a script, and every file outside of it isn't. However, if your server does not have this kind of configuration, you can use the same directory for everything. If you're not sure, you're better off separating the two.
Now that you've chosen the two directories, upload everything in resource-directory to the resource directory you chose, and all files in script-directory to your script directory – duh. Make sure you upload all files in the script directory in ASCII mode. Caution: don't upload the directory itself, just everything contained in it; you don't want to see a directory called resource-directory on your webspace.
Next up: changing the attributes of the files, to give the scripts permission to write to them. This will be done via the FTP SITE CHMOD command; most modern graphical FTP clients have a menu option for this. Change the attributes of the files as follows:
CHMOD 777 (rwxrwxrwx) for the following subdirectories of the script directory and the files they contain, except the .htaccess files.
CHMOD 755 (rwxr-xr-x) for the following files in the script directory's root:
Almost there! If all goes well, you should now be able to open controlpanel.pl (on the server) in your web browser. If everything goes well, you'll see a login screen. If not, please go over the process described above again; should problems persist, then please submit a support request.
Log into the Control Panel with the password you chose. You should now
see the "Edit Setup" button at the bottom. For now, it is recommended that you
only change the "Site Title", "Script URL" and "Time Zone" fields if
If the server is in the time zone you'd like to use for time display, you should leave that field blank, and if the Time::Local module isn't available, you will have no further option. Otherwise, enter the (typically 3-letter) target time zone. Save the information you entered.
Symbio is now ready-to-use. All you need to do now is add the Symbio link to every article you'd like to add comments to. This is done as follows:
First of all, every page you want to use Symbio on will need the initialization code somewhere between the <head> and </head> tag. There are two ways to initialize Symbio:
Server Side Includes: If Symbio is on the same server as the page and the server supports SSI, add the following code:
Now we're going to add a comment link everywhere you want one.
But first, you need to be aware of the fact that every article you want to use Symbio with will need a unique ID. Most web logging systems assign an ID to every post – for example, with Blogger, the article ID will be <$BlogItemNumber$>. If you don't have the means to automatically generate an ID for every article, you'll have to create the IDs yourself; we recommend good old-fashioned numbering, starting from 1. As of version 1.2, Symbio supports most characters in this ID, yet not all. The ID definitely has to consist of strictly characters that are allowed in filenames on your system. Therefore, you'll probably want to avoid using characters other than alphanumeric. Generally, using only numbers will absolutely suffice.
Now that you understand the identification concept, here's the code you need to place wherever you want a comment link:
You may also want to use a non-default link text for one or more articles. To achieve this, all you need to do is add an extra parameter to the function call, i.e. change the second line to:
For example, say you're criticizing the animated series Futurama and the article you use for that is identified as FuturamaBashing. If you wish to use a comment link other than the default, you would enter:
And in case you didn't quite catch that: to use the default link text (which you can define in your Symbio Control Panel), just drop the second parameter as follows:
This last example is probably the one you'll be using most, be it with a different article ID every time, obviously.
This step is optional. It allows you to take advantage of the RSS and TrackBack features that Symbio has to offer.
To find the URL to your RSS feed, surf to the Control Panel's "RSS Feed Configuration" component. Just link to that exact URL and your visitors will be able to syndicate your comment feed. You may however want to complete the configuration for that component first.
As for TrackBack, since Symbio acts both as a TrackBack server and a TrackBack client, there are a few things you need to know if you want to take advantage of it:
To act as a TrackBack server, you can provide a TrackBack URL in two ways and it is advised that you implement both.
The first is to mention the appropriate TrackBack URL near every article. Once you've enabled TrackBack in the Control Panel, the TrackBack URL for an article is URL_to_script_directory/trackback.pl/ID – the variable parts are the same as in the comment link code.
Secondly, you can implement TrackBack Autodiscovery. This is a mechanism that allows people's TrackBack clients to find the appropriate TrackBack URL by analyzing the source code of the page they link to. In order to do this, you add the following code for every article:
<!-- <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:trackback="http://madskills.com/public/xml/rss/module/trackback/"> <rdf:Description rdf:about="article_URL" dc:identifier="article_URL" dc:title="article_title" trackback:ping="TrackBack_URL" /> </rdf:RDF> -->
TrackBack_URL is the URL described in the previous item. Next, let's take a look at article_URL. Setting this may be fairly tricky, because it has to be a unique URL that points directly to the article. In addition, it has to be the exact URL that other publishers are going to link to, because TrackBack Autodiscovery relies on matching article URLs. I recommend using something like site_URL?ID, site_URL/ID.html or site_URL#ID. Caution: the code above needs to be added to the file the article URL points to! Lastly, for article_title, you can enter anything you like.
You can also ping TrackBack URLs yourself. To do this, surf to the Control Panel's "TrackBack Client" component and follow instructions.
Believe it or not, but that's it. You can now start using Symbio. Be sure to surf to your Control Panel again to explore your brand new commenting system's spiffy features.