Tclhttpd Tutorials

written July 2005
Google site search


Tclhttpd is a tcl/tk only webserver which can be embedded in other Tcl applications. As well as static html pages and cgi, tclhttpd uses direct URL's which are scripted in Tcl and permanent in the server program. This is a superefficient replacement for cgi. This means that dynamic page code can be static in the server. Old style cgi scripts can also be executed under the server. The server can also be housed within a front end application ( for instance to manage the information that the server delivers ).

Tclhttpd has command line arguments that allow it to be run on different ports, so you can have a totally general server or you can have multiple servers running on different ports, eg a test server running on the same box as the production server. One trick I have found useful is to have two servers on the same website. One basically for customer access {99%read) and a second for admin functions on the site (50%read). This means that slow admin transactions do not hold up fast customer access. Linux handles this instead of requiring the webserver to handle it.

1   Installation

There is effectively no installation. tclhttpd runs out of the unpacked directory. The directory is typically put in Tcl/lib (ActiveTcl/lib).

But there is one bugfix for Windows. In bin/httpd.tcl change "vwait forever" near the bottom to

  if {![info exists tcl_service] && ![info exists tk_version]} {
        vwait forever
Also Windows needs to have a C:tmp directory where logs etc are put.

1.1   Startup

tclhttpd requires a /tmp (C:tmp) directory which may not exist. Create it if it doesnt exist (it will exist under *nix)

cd to the unpacked directory, exec wish then source /bin/httpd.tcl

Take a note of the password that is provided as this gives access to the admin functions, user=debug.

To see pages view http://localhost:8015/manual

1.2   Production operation

Under Windows create a shortcut for
wish.exe C:\Tcl\tclhttpd3.5.1\bin\httpd.tcl -port 80 -docRoot /sambar63/docs -webmaster
this sets the port to the normal 80, specifies a docroot from the docroot of your old webserver you are about to ditch. options -debug 1 and -gui 1 can be used for test and fiddling.

2   Migrating from another webserver

I will use the example of migrating from a simple webserver like Sambar under Windows where the .tcl scripts are automagically invoked using wish. This has to change for tclhttpd and also for general compatability with *nix systems.

To migrate in Windows, copy/rename your cgi scripts from *.tcl to *.cgi and adjust the filetype for .cgi so they are the same as for .tcl. Typically open wish.exe "%1" (set as default), edit wish.exe C:/Tcl/TextEd.tcl "%1"

You can leave the old .tcl files intact, or have them source the .cgi files so that the doc tree will continue to work on the old server.

The next logical move after this is to bring the cgi scripts inside tclhttpd so they dont invoke interpreter overheads all the time. This also means a move from [puts stdout] to writing the webpage to a variable (html) and returning the value. This causes a move from the cgi package to implicit use of ncgi. You may also decide to use the http package.

User scripts are held in the tclhttpd/custom directory. All .tcl files in this directory are sourced on startup. There are already a few files in the custom directory. In particuar there is a dodirs.tcl script which also sources subdirectories which contain files named "startup.tcl" files in any subdirectories (but it does not do what appears to have been intended - you will need to rewrite it). This may be useful if you have special requirements and you will probably want to change the dodocs.tcl script.

The simplest way of integrating the website into tclhttpd is to use Dircet_Url. This procedure is a relational entry which associates a url prefex with a prodecure name prefix. However this applies to everything under the url prefix. You can have the url foo/index as a procedure under [Direct_Url /foo foo] by having [proc foo/index args {}] but you cannot also have cgi calls under the same prefix such as foo/basket.cgi

The procedure must have an args which contains the form name list returned from the webpage. ncgi and cgi packages do not need to be used. Webpage content is typically appended in a variable called html which is returned at the end of the procedure. Content-type can be omitted, text/html is assumed.

If the value returned is something else such as an image you need to set a global variable with the same name as the procedure with the content-type.

set foo/index image/jpeg
proc foo/index args { ...}
A simple way of converting a cgi system to Direct_Url is to create procedures called foo/bar.tcl. These are in a way a legacy name but serve the purpose. You can have foo/bar as well and have foo/bar.tcl invoke foo/bar
proc foo/bar.tcl args {
    return [ eval [ concat foo/bar $args ] ]
This means that links to your site are preserved as you migrate, both your own links and search engine links.

2.1   Configuring tclhttpd

Tclhttpd does not have a configuration interface. Instead startup scripts are used.

tclhttpd.rc has configuration options for server interface with the network.

httpdthread.tcl has configuration options for the server interface with the webpages.

Doc_Root defines the top-level directory, or folder, for your web-visible file structure.
Doc_AddRoot /addroot htdocs_2 allows you to merge a second file system into the URL tree. I am not sure of the exact nature of this merge.

DirList_IndexFile		index.{tml,html,shtml,thtml,htm,subst}
Doc_ErrorPage		/error.html
Doc_NotFoundPage	/notfound.html
Httpd_Webmaster		$Config(webmaster)
Default directory listings if no index file is found. This can be changed.

2.2   Default page

The default page is taken as the first page found in the following list:
So typically this will be index.html. The most flexible way to arrange this is to have a redirect for index.html to index.cgi. To do this put this index.html script file in your document root:
<meta http-equiv='refresh' content='0; URL=index' /> 
There is a Redirect_UrlSelf command but this does not appear to get invoked for default pages.

The index Url is a [proc index args {}] typically in a index.tcl script in the custom directory with a Direct_Url:

Direct_Url  /index  index
In the index.cgi script output the page you want to show using [puts] commands. Because this is a default page you dont have to mess with parameters. I use this script to redirect viewers to a particular directory based on the domain name that is used to access the server.

©2000 - 2006 WEBSCOOL This page last updated 20 May 2006. All rights reserved - including copying or distribution of any portion of this document in any form or on any medium without authorisation. For more regarding the copyright.