This is a working comments system for web pages.

It allows visitors to your website to attach comments to pages which you
designate. As an administrator you can remove comments.

It demonstrates various mod_caml features including accessing a
database, persistent database connections for efficiency, implementing
logins using session cookies, and templates.

Prerequisites
-------------

You will need to have a PostgreSQL database, and the PostgreSQL OCaml
development libraries installed (check if you have
$OCAMLLIBDIR/postgres/). Under Debian this package is called
libpgsql-ocaml-dev.

You must have built and installed mod_caml. Before trying to install
this comments system, make sure that basic CGI script functionality is
working by running the simple examples.

If you changed any paths in Makefile.config when installing, then
you'll almost certainly need to hack around in the code. This is not
supposed to be easy.

Setting up the database
-----------------------

Create a PostgreSQL database called "comments" and initialize it by
loading comments_create.sql. You may need to modify this SQL script if
you web server runs as a different user than "www-data" (eg. commonly
webservers run as "nobody").

Setting up Apache
-----------------

Ensure environment variables are set so that Apache can access the
"comments" database. If Apache and PostgreSQL are running on the same
machine, then it's likely you won't need to do anything.

Add the following to your Apache configuration:

CamlLoad /usr/share/mod_caml/registry.cmo
CamlLoad /usr/share/mod_caml/comments.cmo
Alias /caml-icons/ /usr/share/mod_caml/caml-icons/
Alias /caml-bin/ /usr/share/mod_caml/caml-bin/

<Location /caml-bin>
  SetHandler ocaml-bytecode
  CamlHandler Registry.handler
  Options ExecCGI
  Allow from all
</Location>

Make sure SSI (server-side includes) are enabled.

Most of the look and feel of the comments system is driven through
CSS. You may like to create a stylesheet /css/default.css. Try
downloading and modifying this one:
http://www.annexia.org/css/default.css

Setting up your site
--------------------

Create an SSI (.shtml) page on your site which includes this:

<!--#include virtual="/caml-bin/show_comments.cmo" -->

Restart Apache and visit this page. If all is working, you should see
a "Post a comment" link, and some other links. If it's not working,
then check the Apache error log for errors.

Testing
-------

Try posting some comments, and see if they appear.

Note that you can have a common SSI include file containing the
show_comments link on several pages, and the comments system is smart
enough to keep the comments for different pages separate. (To see how
this is done, look at show_comments.ml).

Creating an administrator account
---------------------------------

Examine the comments_users table (using a tool such as psql). If you
have posted some comments, then there may be one or more rows in this
table.

Users with a userid < 10 are administrators. The only way to create an
administrator is to hack the database.

Pick a user to be administrator, and do:

UPDATE comments_users SET id = 1 WHERE name = 'Richard Jones';
UPDATE comments_users SET password = 'xyz' WHERE name = 'Richard Jones';

(obviously change the name to the administrator name, and the password
to the desired password).

Try logging in using the 'Administrators' link. You should now be able
to delete comments on the 'View comments on all pages' page.

Guide to the code
-----------------

'comments.ml' is a library containing common functions shared by all
scripts.

All other '*.ml' files are CGI scripts. Many of them have an associated
template ('*.html') file.

'delete_comment.ml' is probably the simplest CGI script of all. It
doesn't even use a template.

'comments.ml' and 'comments_login.ml' contain the session cookie /
login code.

'view_comments.html' is probably the most complex template of the lot,
and therefore a good example to follow.
