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 a daemon process on your server.
It might be difficult if you're using 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 that handles browsing
message archives. When installed, this script becomes
'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 are to 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 needs 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/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.
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
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.