Instaweb : Instant Web Publishing Tool

Instaweb : Instant Web Publishing Tool
======================================

By Noel Welsh (noelwelsh at yahoo dot com) 

This manual documents Instaweb version 1.5
Time-stamp: <2006-07-12 16:16:08 noel>

Keywords: _instaweb_, _servlet_, _internet_, _web_


Introduction
============

Instaweb is a simple tool that makes it easier to run
servlets in the PLT web server.

It does the following:

  - configures the web server to run a single servlet

  - runs the web server in a handy interactive shell


Usage
=====

Simply require the instaweb library, and call the function
instaweb with the name of the servlet you want to run, and
optionally the port number and IP address to listen on.  If
the IP address is #f or not given the server will listen on
all addresses.  The servlet must be in the current directory
as determined by the current-directory parameter.  If you
want to make your use of Instaweb unaffected by the value of
current-directory, use the instaweb-here macro, which
parameterizes current-directory to the directory of the file
containing the call.

Example:

  (require (planet "instaweb.ss" ("schematics" "instaweb.plt" 1)))
  (instaweb "my-servlet.ss" 5678 "127.0.0.1")

or

  (require (planet "instaweb.ss" ("schematics" "instaweb.plt" 1)))
  (instaweb-here "my-servlet.ss"5678 "127.0.0.1")

> (instaweb servlet [port] [ip-address])
instaweb : string [integer] [(U string #f)] -> void

The file name of the servlet 

The optional port to listen on, defaults to 80

The optional IP address to listen on, or #f (the default)
for all addresses

> (instaweb-here servlet [port] [ip-address])
Syntax

Arguments are as for instaweb above.


Tips and Caveats
================

If you want to run a Instaweb launched servlet on a server
you probably don't want an interactive terminal.  This is ok
-- Instaweb will detect when it doesn't have a terminal and
so avoid filling your logs with rubbish.  Say run-servlet.ss
is the file that launches your servlet.  The recommended way
to run such a setup on a server is:

  mzscheme -qr run-servlet.ss

The important bit here is the 'r' flag, which runs MzScheme
without a REPL.  You probably want to spawn a new process to
run MzScheme, and prevent signals from interferring with it,
a better line might be:

  nohup mzscheme -qr run-servlet.ss &

The web server requires servlets live in a directory called
servlets.  Hence instaweb creates this directory and copies
your servlet to it.  This means if your servlet requires any
modules using relative paths those modules probably won't be
found.  To get around this put your support modules into a
collection that you install via a .plt or Planet.  Then
require them with the (lib ...)  or (planet ...) form as
appropriate.

Instaweb doesn't clean up after itself.  This is a
deliberate decision as you'll probably want to populate the
web root directories with static files etc. over time.


Thanks
======

Matthew Flatt, Jens Axel Soegaard, and Dave Herman for
suggestions for dealing with a missing terminal, and
suspending the main thread

Eric Hanchow, for pointing out documentation typos