TightURL
[ class tree: TightURL ] [ index: TightURL ] [ all elements ]

INSTALL

                            TightURL
                          Installation

  Installing TightURL
  -------------------

  1. Untar the file: tar zxvf tighturl-0.1.tar.gz

  2. Move the files in the directory to where you want to run
     your installation of TightURL.

  3. Rename tighturl.php to index.php (default.php for IIS) if desired.

  4. Create a MySQL database if necessary.

  5. Create the TightURL table. Edit tighturl.sql if you don't want
     your table named "tighturl", then:
     mysql -p yourdatabase <tighturl.sql

  6. Edit the config settings in tighturl.config.inc.php
     You will need to change at least the MySQL database settings.
     See 'Configuration Settings' below.

  7. Decide if you want to use 'Reserved URLs'.  These are turned on
     by default because it is problematic to turn them on in an
     active TightURL.  See 'Reserved URLs' below.

  8. If you can set a custom 404 page for your Web site/directory, you
     can set it to tighturl/index.php and get shorter URLs.  To take
     advantage of this, set $compress="1" in tighturl.config.inc.php.

  9. Change the $svcname in tighturl.config.inc.php if desired.

 10. Edit the master site HTML template tighturl.tmpl if desired.
     See 'TightURL Templates' below.

 11. Edit the HTML sub-templates if desired.  These are:
     A. tighturl.main.tmpl : HTML shown for your TightURL homepage
     B. tighturl.save.tmpl : HTML shown when a URL is saved
     C. tighturl.help.tmpl : HTML shown for Help info (may not exist yet)

     See 'TightURL Templates' below for more information.

  Configuration Settings
  ----------------------

  These are the configuration (variables) settings that can and should
  be changed in tighturl.config.inc.php :
  
  MySQL:
    $dbhost  : DNS name of your MySQL server
    $dbuser  : MySQL user name
    $dbpass  : password for MySQL user name
    $dbname  : database containing TightURL's table
    $dbtable : name of TightURL's table

  Operating modes:
    $FOFMethod : Use 404-Method to compress TightURLs?
      0 = FALSE (full URL path (not compressed) or mod_rewrite TightURLs)
      1 = TRUE  (404-Method compressed TightURLs)
    $Reserved  : Use Reserved URLs?
      0 = FALSE (All URLs are available as TightURLs)
      1 = TRUE  (Some URLs are reserved for pages in the TightURL)
	
    URIBL variables:
      $uribl    : Array of URIBLs to check
      $uriblurl : Array of Web sites corresponding to URIBLs checked

  Text strings and style variables:
    $svcname    : One-word name for your TightURL service
    $verbtext   : One-word name for the act of tightening URLs
    $pasttext   : Past-tense name for a tightended URL
    $tagline    : "tag line" for your TightURL service
    $headcolor  : Color for the TightURL <H1> HTML header
    $tablecolor : Color for the table the URL input field appears in
    $copystart  : 4-digit year of start of your copyright on your content.
                  defaults to current year if not given.

  NEVER CHANGE SETTINGS IN tighturl.php OR YOU WILL LOSE YOUR CHANGES
  any time you upgrade to a newer version of TightURL.  Always put your
  configuration settings in tighturl.config.inc.php where they will 
  survive upgrades.  Values in tighturl.config.inc.php override the
  defaults (garbage) in tinyurl.php .

  Reserved URLs
  -------------

  Because we use Base-36 numbers as TightURL IDs, as time goes on,
  certain desirable URLs will be issued that we might want to keep
  for ourselves.

  For instance, the letters 'faq' are well-understood around the Internet
  to mean "Frequently Answered Questions".  We might want to use the URL
  http://example.com/faq to point to our FAQ page, rather than issue it
  as a regular TightURL to a random visitor.  Reserved URLs allow you to
  specify Base-36 IDs that should never be issued as TightURLs.

  There are two kinds of Reserved URLs.  External (implicit) and Internal
  (explicit) Reserved URLs.

    External Reserved URLs:
       
       Any URL which exists in your Web space will be served up by
       your Web server, and not TightURL.  For this reason, any URL
       reasonably within your TightURL ID space that you want to use
       with your TightURL site itself should be reserved so that you
       don't issue a TightURL to anyone that won't actually work.

       For example, if you have a directory named: /www/example.com/faq
       your Web server will attempt to serve index.html from within
       that directory, and TightURL will never even see the request.
       This kind of reservation is implicit, and TightURL must be
       made aware of it.

    Internal Reserved URLs:
      
      Any URL which does not exist in your Web space but is Reserved
      within TightURL will cause TightURL to look for a correspondingly
      named TightURL Template, and serve that.  If the template does
      not exist, a 404 error is generated.

      For example, if you have reserved the ID 'faq', and TightURL sees
      a request for this reserved ID, it will attempt to open a
      template named tighturl.faq.tmpl and return that to the browser.

  It is VERY IMPORTANT that you decide what your Reserved URLs will be
  before your TightURL service is put into operation, or else you run
  the risk of wanting to reserve a URL that's already been issued as
  a TightURL to someone.  For example, by the time you've issued your
  19826th TightURL, you will have lost the opportunity to use 'faq' as
  a Reserved URL, because decimal (Base-10) number '19826' is number 
  'faq' in sexigesimal (Base-36).

    Reserving URLs:
      
      To reserve a URL, add it to the configuration array $ReservedURL .
      The following URLs are reserved by default:

        faq, help, code, source, docs, cvs, arch, url,
        about, admin, setup, svn

  There is little point in reserving URLs larger than 5 charcters long.
  The first 6 character ID is '100000' sexigesimal, which would be far
  past your 60 millionth TightURL issued. Since each additional Reserved
  URL adds a little more processing time, you don't want to add URLs 
  that will never be issued anyway.

  TightURL Templates
  ------------------
  TightURL supports a simple variable-substitution templating system with
  one level of template nesting.

  The outer template is *always* the main site template, tighturl.tmpl .
  This template controls your site design and is *always* used to generate
  output pages to the browser.
   
  The inner template is *always* one of the following sub-templates 
  (or no sub-template):
    tighturl.main.tmpl : HTML shown for your TightURL homepage
    tighturl.save.tmpl : HTML shown when a URL is saved
    tighturl.help.tmpl : HTML shown for Help info (may not exist yet)
    (none)             : No inner template.

  Please note that many screens are generated using only the main site
  (outer) template.  All error screens are generated this way.

  The variables supported by TightURL Templates are:

    $HTML        : In the innermost or only template, replaced by a HTML
                   message from TightURL.  In an outer template, it is
                   replaced by contents of the inner (sub-)template.
                   You should never remove this variable from a template.
    $URL         : Replaced by browser submitted URL.
    $URLLEN      : Replaced by lenghth of the submitted URL.
    $TIGHTURL    : Replaced by TightURL generated by the submission.
    $TIGHTURLLEN : Replaced by length of the generated TightURL.
    $DIFF        : Replaced by difference in length between URLs.
    $INPUT       : Replaced by submitted URL for use when there has
                   been an error detected in the input.
    $SVCNAME     : Replaced by name chosen for your TightURL service.
    $HEADCOLOR   : Replaced by color value chosen for <H1> HTML tags.
    $TABLECOLOR  : Replaced by color value chosen for the table.
    $TAGLINE     : Replaced by "tag line" for your TightURL service.
    $CPASTTEXT   : Replaced by capitalized past tense description of
                   tightened URLs.
    $PASTTEXT    : Same as $CPASTTEXT, but first letter not capitalized.
    $CVERBTEXT   : Replaced by capitalized verb description of your
                   TightURL service.
    $VERBTEXT    : Same as $CVERBTEXT, but first letter not capitalized.
    $COPYRIGHT   : Replaced by generated copyright string created from
                   $copystart config value and current year.
    $URIBLS      : Replaced by HTML showing URIBLs being checked.
    $HOST        : Replaced by hostname of Web site.
    $SELF        : Replaced by the URL path to the TightURL script.
    $TIGHTURLVER : Replaced by the TightURL running version number.

  Using "The 404-Method" with Apache
  ----------------------------------

  The "404-Method" refers to instructing your Web server to direct
  all requests that generate a "Not found" error (which is an HTTP
  error code 404) to the TightURL script.  By doing this, TightURL
  will run for URLs in your TightURL site that don't exist, such
  as would be the case for http://example.com/tighturl.php/xxyy
  The xxyy is a TightURL ID number, not an actual Web page in your
  site.  By sending non-existent page requests to the TightURL script,
  you can look up those IDs and issue an HTTP Redirect without the
  need for mod_rewrite.

  To use the 404-Method, set $FOFMethod=1 in tighturl.config.inc.php.

  Then put this in your .htaccess file:
  
      ErrorDocument 404 /index.php

  This change should take effect immediately after saving .htaccess .
  If it doesn't work, make sure you have AllowOverride FileInfo on
  in the directory you're running TightURL from.
  
  Alternatively, put The following line in your httpd.conf in the
  appropriate Directory section (and VirtualHost if applicable):
  
        ErrorDocument 404 /index.php

  You will need to reload your Apache configuration for this change
  to take effect.

  See the Apache documentation for more information.
  http://httpd.apache.org/docs/mod/core.html#errordocument
  http://httpd.apache.org/docs/mod/core.html#allowoverride

  Adding more URIBLs
  ------------------
  
  In the event other URIBLs beside SURBL become available, and you wish
  to check those also, edit $uribl and $uriblurl in 
  tighturl.config.inc.php .
  
  To add a new URIBL named uribl.example.com whose Web site is located
  at http://www.example.com 
  
  Change this:
  
      $uribl = array("multi.surbl.org");
      $uriblurl = array("www.surbl.org");

  To this:

      $uribl = array("multi.surbl.org","uribl.example.com");
      $uriblurl = array("www.surbl.org","www.example.com");

  You can add as many URIBLs as you want this way.


Documentation generated on Mon, 25 Oct 2004 06:48:54 -0400 by phpDocumentor 1.3.0RC3