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.

  1. 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.

  2. 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.

  3. 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. $password = 'ilovesymbio';. To avoid problems, it is recommended that you only use alphanumeric characters.

  4. Now we're going to upload the scripts to your webspace. You'll need two main directories:

    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.

  5. 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.

  6. 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:

  7. 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.

  8. 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 necessary.
    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.

  9. 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:

    1. 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:

        <!--#exec cgi="path_to_script_directory/index.cgi"-->
      • Remote JavaScript: If the installation does not meet the requirements for the first option, you can have the user's browser load the comment data separately, using the following code:

        <script src="URL_to_script_directory/index.cgi?mode=js"
        type="text/javascript"></script>

    2. 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:

      <script type="text/javascript"><!--
      linkComments("ID");
      //--></script><noscript><a
      href="URL_to_script_directory/index.cgi?id=ID&amp;mode=view"
      target="_blank">comments</a></noscript>

      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:

      linkComments("ID", "text");

      In case you're wondering what this piece of HTML stands for, here's a short explanation… The linkComments JavaScript function, which has been defined in the initialization process, inserts a comment link, with the number of comments – you can change its appearance in the Control Panel. The <noscript> code on the other hand is used only when the user's browser does not support JavaScript. It inserts a standard link, which opens the comment page in a new window; comments is the text that will be displayed for the link, so you can change that if you like. If you do not wish to provide support for older browsers, you can leave out everything that comes after </script>.

    3. 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:

      <script type="text/javascript"><!--
      linkComments("FuturamaBashing", "Your thoughts on Futurama?");
      //--></script><noscript><a
      href="URL_to_script_directory/index.cgi?id=FuturamaBashing&amp;mode=view"
      target="_blank">Your thoughts on Futurama?</a></noscript>

      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:

      linkComments("FuturamaBashing");

      This last example is probably the one you'll be using most, be it with a different article ID every time, obviously.

  10. This step is optional. It allows you to take advantage of the RSS and TrackBack features that Symbio has to offer.

    1. 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.

    2. 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.

        1. 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.

        2. 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.

  11. 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.