Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
183 lines (128 sloc) 7.05 KB
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 privildge 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.