                  Hakmatak Installation and Configuration

Hakmatak provides useful modules and tools for creating w10n applications.

1. Installation

After obtaining hakmatak-X.X.X.tar.gz, do the following:

$ tar zxvf hakmatak-X.X.X.tar.gz
$ cd hakmatak-X.X.X

As root, do

# python setup.py install

Besides modules, two command line tools are installed:
hakmatakread and hakmatakwrite.

To test, find a text file under ./data/txt inside hakmatak-X.X.X, and run

$ hakmatakread --type bytearray ./data/txt/test0.txt "/"

The text file is parsed as w10n type "bytearray" and the
meta information of tree root is returned in JSON format.
For more about w10n, please read ./doc/w10n.txt.

Currently Hakmatak contains store readers for two w10n types:
"example.basic" and "bytearray", which are primarily used for dev
and debug purpose. Please check http://hakmatak.org for applications
that support more "realistic" w10n types.

2. Web Service Configuration

Included in Hakmatak source are two web applications:
(a) hakmatak/wsgi/index.py
a directory listing service application that checks for webifiable entries.
(b) hakmatak/wsgi/webify.py
a w10n service application that webifies supported data stores.

Both can be set up as either CGI or WSGI application.
When configured for Apache web server, mod_rewrite is used to
rewrite w10n URLs into ones suitable for hakmatak/wsgi/webify.py.

2.1 CGI on Apache

Warning: CGI and WSGI are mutually exclusive in operation.
If you want to set up WSGI, jump to Section 2.2 below directly.

There are different ways to enable CGI scripts on an Apache web server.
Please consult Apache manual for details. In our example below,
ScriptAlias directive is used.

Assuming a linux host with default Apache httpd installation,
listed below are the steps to configure hakmatak-1.1.1. Please adjust
accordingly for a newer version of Hakmatak.

(1) Create a non-root user called "webifier". Its home dir is /home/webifier.

(2) As user "webifier", create dir /home/webifier/wsgi/hakmatak and
copy {index,webify}.py in Hakmatak source to it,

$ mkdir -p /home/webifier/wsgi/hakmatak
$ cp -avi hakmatak-1.1.1/hakmatak/wsgi/index.py /home/webifier/wsgi/hakmatak/
$ cp -avi hakmatak-1.1.1/hakmatak/wsgi/webify.py /home/webifier/wsgi/hakmatak/

Make sure dir /home/webifier/wsgi/ is recursively readable
by Apache web server owner/user, usually, called "apache".

(3) Copy cgi.hakmatak.conf in Hakmatak source to /etc/httpd/conf.d/,

# cp -avi hakmatak-1.1.1/supp/cgi.hakmatak.conf /etc/httpd/conf.d/

and modify it per your requirement by following inline comments inside.

(4) Copy test files to /var/www/html/test/data,

# mkdir -p /var/www/html/test/data
# cp -avi hakmatak-1.1.1/data/txt /var/www/html/test/data/

(5) Restart the web server,

# /etc/init.d/httpd restart

(6) Point your browser to http://localhost/test/data/txt/,
you should be able to see a list of files, of which some are labeled
as "webifiable" with an folder icon. Click on any one of them,
you can browse inside the file as it is webified following the w10n
specification.

2.2 WSGI on Apache

Warning: CGI and WSGI are mutually exclusive in operation.
If you want to set up CGI, go back to Section 2.1 above.

WSGI is considered as CGI replacement.

To enable Apache for WSGI, mod_wsgi must be compiled and installed.
The mod_wsgi project is hosted at http://code.google.com/p/modwsgi/
and its source can be downloaded from
http://code.google.com/p/modwsgi/downloads/list.
Hakmatak has been tested only for mod_wsgi-2.X.

Assuming an rpm-based linux host with default Apache httpd installation,
listed below are the steps to configure hakmatak-1.1.1. Please adjust
accordingly for a newer version of Hakmatak.

(0) Compile and install mod_wsgi for Apache web server

$ tar zxvf mod_wsgi-2.X.tar.gz 
$ cd mod_wsgi-2.X
$ ./configure
$ make

If the host is 32 bit, do

# cp -avi .libs/mod_wsgi.so /usr/lib/httpd/modules/

If the host is 64 bit, do

# cp -avi .libs/mod_wsgi.so /usr/lib64/httpd/modules/

Note (a): The httpd-devel rpm must be installed in order to build
mod_wsgi module.

Note (b): If mod_python has been installed with httpd, it must be removed
from the system. Otherwise mod_wsgi will not work properly. mod_python is
the old way to integrate python applications into Apache httpd. New python
applications should be created with mod_wsgi. To remove mod_python, do:

# rpm -e mod_python

Note (c): It is always a good idea to stop httpd before installing
or uninstalling Apache modules.

(1) Create a non-root user called "webifier". Its home dir is /home/webifier.

(2) As user "webifier", create dir /home/webifier/wsgi/hakmatak and
copy {index,webify}.py in Hakmatak source to it,

$ mkdir -p /home/webifier/wsgi/hakmatak
$ cp -avi hakmatak-1.1.1/hakmatak/wsgi/index.py /home/webifier/wsgi/hakmatak/
$ cp -avi hakmatak-1.1.1/hakmatak/wsgi/webify.py /home/webifier/wsgi/hakmatak/

Make sure dir /home/webifier/wsgi/ is recursively readable
by Apache web server owner/user, usually, called "apache".

(3) Copy wsgi.hakmatak.conf in Hakmatak source to /etc/httpd/conf.d/,

# cp -avi hakmatak-1.1.1/supp/wsgi.hakmatak.conf /etc/httpd/conf.d/

and modify it per your requirement by following inline comments inside.

(4) Copy test files to /var/www/html/test/data,

# mkdir -p /var/www/html/test/data
# cp -avi hakmatak-1.1.1/data/txt /var/www/html/test/data/

(5) Restart the web server,

# /etc/init.d/httpd restart

(6) Point your browser to http://localhost/test/data/txt/,
you should be able to see a list of files, of which some are labeled
as "webifiable" with an folder icon. Click on any one of them,
you can browse inside the file as it is webified following the w10n
specification.
