Chaton (pronounced like [sha-ton]) is a comet-based webchat server.
It is a collection of CGI scripts, daemon programs and other scripts.

Prerequisites:

- Make sure you can run daemon processes on your server.
  It might be difficult if you're using a shared hosting
  service.

- It is also desirable that you can make your own crontab.

- The server should also run httpd that is capable to run
  CGI.  The server should be configured so that you can
  do SetHandler in .htaccess file.

- Gauche 0.8.14 or later.  You can install it under
  your home directory.


Files:

  The following files are scripts that cooperates to make Chaton
  work:

    chaton-entry    This is a CGI script invoked when the room
          is accessed via web browsers.  This script creates the
          "outer frame" of the chat room page, and make the "inner
          frame" connect to the Comet server.

    chaton-viewer   This is the Comet server responsible to
          distribute room contents.   It must run as a daemon.
          Currently you have to run one daemon process per
          one chatroom.  The actual installed script is named
          'chaton-viewer-$ROOM', where $ROOM is the room name.

    chaton-poster   This is a CGI script that handles message
          posting.  The actual installed script is named
          'chaton-poster-$ROOM'.

    chaton-browser  This is a CGI script to browse message archives.
          When installed, this script is renamed to 'a', for the sake
          of shorter permalinks.

    chaton-archiver  This is a script file that archives message
          logs.  This script must be run daily.

    chaton-badge    This is a CGI script that generates "badge"
          of the room.  When installed, this script becomes 'b',
          for conciseness.

    chaton-apilogin  This is a CGI script where the client programs
          first contact through API.  When installed, this script
          becomes 'apilogin'.


 The following files consist the client-side contents:

    chaton.js   The javascript that implements client-side operations.
          The same file is read from both the outer content and
          and from the content inside the iframe.
          Upon installation, this file is renamed to 'chaton.XXXXXX.js'
          where XXXXXX is a unique string, to avoid caching by
          browsers.

    chaton.css   The stylesheet.  Used by both the outer content
          and the content inside the iframe.

  Additionally, 'chaton.scm' implements common funcionalities used
  among server-side scripts, and 'htaccess' is the skeleton of
  '.htaccess' file for each room.


Directory structure:

  $BINDIR        A directory where server-side programs (chaton-viewer-*
                 and chaton-archiver-*) will go.  You may want this
                 directory to be in your PATH for the convenience,
                 although not necessarily.

  $DATADIR       A directory where the chat messages and other stuff
                 are stored.  Recommended not to be under the directory
                 visible via httpd.
                 Each chatroom must have distinct $DATADIR.

    $DATADIR/data   Subdirectory where message data goes into.  CGI
                 scripts need to write into this directory.

    $DATADIR/data/current.dat   Current message data.  Typically it
                 contains around one-day worth of postings.   The
                 chaton-archiver script removes old messages from this
                 and stores them to archived data.

    $DATADIR/data/YYYY/MM/DD.dat  Archived data.   Created by
                 chaton-archiver script.   Chaton-archiver also sets
                 the today's data file as a symlink to the current.dat
                 file.

    $DATADIR/logs/comet.log  Access log file from the Comet server
                 (chaton-viewer-*).

    $DATADIR/logs/archive.log  Log from the archiver.


  $HTDOCSDIR     A directory where the content accessed by browsers
                 will go.   Each chatroom must have distinct $HTDOCSDIR.
                 The httpd should honor .htaccess in this directory.

    $HTDOCSDIR/.htaccess     Some DirectoryIndex and SetHandler directives.

    $HTDOCSDIR/entry         The main entry CGI.  We use DirectoryIndex so
                 that this script is kicked when the client access
                 this directory.

    $HTDOCSDIR/chaton.css, $HTDOCSDIR/chaton.XXXXXX.js
                 CSS and javascript files.

    $HTDOCSDIR/chaton-poster-$ROOM   A CGI script to post the message.

    $HTDOCSDIR/a   A CGI script to browse the archived messages.  From
                 the web browsers, archived messages are accessed
                 as 'http://yourdomain.example.com/.../$ROOM/a/YYYY/MM/DD'

    $HTDOCSDIR/var           A directory holds some transient data.  This
                 directory must be writable both by CGI scripts and
                 the user running viewer and archiver.

    $HTDOCSDIR/var/status.{js,scm}  The comet server periodically dumps
                 the room status into these files.  You can poll these files
                 to find out the current status of the room.
                 See http://chaton.practical-scheme.net/doc?Retrieving%20Room%20Status
                 for the details.

    $HTDOCSDIR/var/index.rdf
    $HTDOCSDIR/var/seq       These are written by chaton-poster-$ROOM script.
                 The index.rdf serves RSS.  The seq file is a text file contains
                 a number; they can be read by the clients to show # of unread
                 messages.

Build a chat room:

  To build a chat room, first you prepare configuration file.
  Copy 'sample.conf' and follow the directions.

  The 'sample.conf' file includes two auxiliary files, 'conf/site.conf'
  and 'conf/appearance.conf'.   You MUST edit 'conf/site.conf' to reflect
  your site settings; the default values are useless to you.  On the
  other hand, you can leave 'conf/appearance.conf' as is if you don't
  need to change it.

  Other than those included .conf files, each chat room MUST have
  distinct copy of configuration file.  Especially, make sure
  that the room name, comet port number, url path, htdocs dir and
  data dir are all unique for each chat room.

  Once you prepare conf file, run build-site script:

    gosh ./build-site yourroom.conf

  This copies necessary files, with modifying them according to
  the configuration settings.

  For your convenience, you can list multiple conf files in the
  file 'rooms', one per line.  Then simply the following command
  runs build-site for every room you have.

    make install

  If you run cgi scripts in a different user privilege than yourself
  (that is, you're not using suexec), you need to adjust permissons
  of some directories.  See the above directory structure descriptions.
  The recommended way is to use common group permissoins and make those
  directories group writable.
  It'd be nicer to do so automagically by build-site script, but not yet.


Run a chat room:

  You have to run chaton-viewer-$ROOM as a background process.

  You also have to set up chaton-archiver-$ROOM to be executed
  once a day, probably using cron.