gf-core/deprecated/server/README

== Requirements ==

- cabal-install
  * See quick installation instructions at the bottom of 
     http://hackage.haskell.org/trac/hackage/wiki/CabalInstall

- GF installed as a Cabal package
   $ (cd ../.. && cabal install)

- FastCGI development kit
  (MacPorts)   $ sudo port install fcgi
  (Ubuntu)     $ sudo apt-get install libfcgi-dev

- Google Web Toolkit
  - Download from http://code.google.com/webtoolkit/
  - Unpack somewhere.
  - Set $GWT_CLASSPATH to point to the GWT JAR files. For example:
    $ export GWT_DIR="/Users/bringert/src/gwt-mac-1.5.3"
    $ export GWT_CLASSPATH="$GWT_DIR/gwt-user.jar:$GWT_DIR/gwt-dev-mac.jar"


== Building ==

- Build pgf.fcgi. This will use cabal to install the dependencies (cgi, fastcgi, json, utf8-string).
  $ make

- Build small example grammar:
  $ make food.pgf
  $ cp food.pgf grammar.pgf


== Running (lighttpd) ==

- Install lighttpd
  (MacPorts)   $ sudo port install lighttpd
  (Ubuntu)     $ sudo apt-get install lighttpd

- Run pgf.fcgi with lighttpd:
  $ make run


== Testing ==

- First test from the command-line, since debugging is harder from the AJAX UI:
  $ curl 'http://localhost:41296/pgf/grammar.pgf/translate?input=this+fish&cat=Item&from=FoodEng'

- Non-GWT AJAX UI: 
   See http://localhost:41296/simple-client.html

- GWT translator:
  $ make gwt-translate
  Then see http://localhost:41296/translate/

- GWT fridge poetry:
  $ make gwt-fridge
  Then see http://localhost:41296/fridge/

- GWT morphology:
  $ make gwt-morpho
  Then see http://localhost:41296/morpho/

  The MorphoService.hs module has build-in paths to the grammar that will be loaded.
  This have to be fixed by hand

== Running (Apache) ==

Note: This is more complicated, and the instructions may not be up to date.

- Make sure that your web server supports FastCGI. For Apache on OS X,
  do this:

$  curl -O http://www.fastcgi.com/dist/mod_fastcgi-2.4.6.tar.gz
$  tar -zxf mod_fastcgi-2.4.6.tar.gz 
$  cd mod_fastcgi-2.4.6/
$  apxs -o mod_fastcgi.so -c *.c
$  sudo apxs -i -a -n fastcgi mod_fastcgi.so

- Make sure that your web server knows that gf.fcgi is a FastCGI
program.

- Make sure that you are allowed to run FastCGI programs in the 
directory that you use.

- With large grammars, gf.fcgi may take long enough to start that the web server
thinks that the program has died. With Apache, you can fix this by adding 
"FastCgiConfig -startDelay 30" to your httpd.conf. 

These sections from my Apache config fixes the above two 
(some of this may be fixed by the second apxs command above):

(On OS X, this is in /etc/httpd/httpd.conf)

LoadModule fastcgi_module     libexec/httpd/mod_fastcgi.so
AddModule mod_fastcgi.c

<IfModule mod_fastcgi.c> 
  FastCgiIpcDir /tmp/fcgi_ipc/ 
  AddHandler fastcgi-script .fcgi 
  FastCgiConfig -startDelay 30
</IfModule>


(On OS X, this is in /etc/httpd/users/bringert.conf)

<Directory "/Users/bringert/Sites/">
    Options Indexes MultiViews FollowSymlinks ExecCGI
    AddHandler cgi-script .cgi
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

- If you have changed the web server config, you need to restart the web server
 (this is also useful to get a clean slate if you end up with dead or resource-hogging 
 FastCGI processes):

$ sudo apachectl restart

- If Apache complains about a syntax error on the FastCgiIpcDir line, try deleting
  any existing /tmp/fcgi_ipc/ directory:

$ sudo rm -rf /tmp/fcgi_ipc/

- Copy or symlink this directory to your web directory.

- First test from the command-line, since debugging is harder from the AJAX UI:

$ curl 'http://localhost/~bringert/gf-server/gf.fcgi/translate?input=this+fish&cat=Item&from=FoodEng'

- Check server logs (e.g. /var/log/httpd/error_log) if it doesn't work.

- Go to SERVER_URL/simple-client.html in your web browser.