quick server pages
   
Manual page for Setting(up)

Setting up a QUISP-powered web site

This process requires that you know something about setting file permissions and creating soft links. You need to have a cgi-bin that you can put files in. Some items herein such as specific URLs and pathnames are installation-specific. These kinds of things are inherently somewhat tricky... if at first you don't succeed, etc. etc.

  • Install QUISP if you haven't already done so.

  • Each QUISP-powered web site will require a directory for files and data. This directory can be located anywhere, and can be owned by any UID.

  • Decide what UID will own the web-site/database, and where the site's directory will be located.

  • As this UID, run the shell script newproject.sh (it's located in the ./bin). It will prompt you for full pathname of the web site directory you want to create, and then build the directory with a few dummy pages and data sets for testing.

  • Go into the new directory. Edit the config file, and change the dbbin entry from path to the full path name of the bin directory where shsql executables reside. This allows quisp to find certain programs it needs. If in future you ever move the shsql executables, you'll need to remember to update this line in the config file.

  • Also in your config file (near the bottom), set HTMLURL and HTMLPATH to values appropriate for your installation. Here are the settings I use on the quisp sourceforge web site:
      varvalue:       HTMLURL=        
      varvalue:       HTMLPATH=/home/groups/q/qu/quisp/htdocs  
    


  • Set (and export) a shell environment variable called SHSQL_DB ... It should contain the full pathname of your project directory. This won't be used by CGI processes, but is used by the command line utilities to locate/select the database.

  • Determine if you are setting up a read-write, or read-only application. More discussion.

  • Copy the quisp executable to your cgi-bin (or create a soft link). If you're setting up a read-write application this must be done by the project owner UID, for read-only it doesn't matter. If you are just demoing or trying QUISP for the first time, stick with the name quisp. More advanced users can name the executable anything desired, for example, mydbcgi, and there can be multiple quisp executables (or links) in your cgi-bin having different names, in order to accommodate multiple QUISP web site projects. If you're using ploticus graphics, there are a few additional considerations.

    If you're setting up a read-write application, the quisp (and quisp_pl) executable should be setuid to the owner of the project/database directory. It should have a permissions mode of 6755 (-rwsr-sr-x); if it doesn't, use a command like this: chmod 6755 quisp (Note that some web hosts may have restrictions on setuid CGI programs.)

    If your quisp application will be read-only, setuid is not required, but all files & subdirectories in your project directory (except logs) must be world-readable (so that the web server can find them). If your application will be writing to ./tmp (as is done with graphics) then ./tmp will need to be world-writable. The ./logs will need to be world-writable if you decide to capture error messages or usage info.

  • Now go to your cgi-bin and make a soft link to your project config file (that was created by newproject.sh). The link should have the same name as the quisp executable (or link) that's in the cgi-bin, with .cnf appended to the end. For example, for quisp name it quisp.cnf. For quisp_pl name it quisp_pl.cnf. If you renamed your quisp executables use the same name with a .cnf tacked onto the end. Some installations have limitations on what files a CGI program can "see"... for example on sourceforge the config file (and other files) could not be opened unless the project directory was located under the quisp htdocs node.


Test drive

After running newproject.sh make sure things are working by accessing some demo material that is automatically installed by newproject.sh:
  • Try an SQL select command from the command line, eg:
    shsql -n "select * from examp_people".

  • Try a test web page. Fire up your web browser and enter a URL that will invoke quisp, via your cgi-bin, eg:
    http://abc.com/cgi-bin/quisp
    The specifics of this URL depend on your local system.
    If all goes well, QUISP should load a test page. If not, use something like this:
    http://abc.com/cgi-bin/quisp?_DEBUG=1
    to print out some diagnostic and environment info. If you still can't get it to work, try your local support team or web server configuration docs (I can't be of much help diagnosing local configuration issues from where I sit).


More test examples

  • A number of examples are available in the distribution ./qexamples directory. You can try them now.. just copy all files from ./qexamples to the pages directory (in the project directory you just built). Then point your browser to:
    http://abc.com/cgi-bin/quisp?rtn=index
    (substitute domain name and cgi bin as appropriate for your installation).
    Note: the graphic example won't work yet... it requires one additional step, below.

  • These examples can also be tried anytime from the quisp web site on sourceforge.


Finishing touches

Do these after achieving success on the test drive.
  • If you're generating graphics using quisp_pl, again edit your config file, uncomment CGIPROG and CGIPROG_PL, and set them appropriately for your installation. Here's what I use on the live demo on sourceforge:
      varvalue:       CGIPROG=/cgi-bin/quisp          
      varvalue:       CGIPROG_PL=/cgi-bin/quisp_pl    
    


  • Because temporary files will accumulate in the project tmp directory, a good practice is to put a find(1) command into the project owner's crontab to run daily or weekly, like this:
      /usr/bin/find /yourprojpath/tmp  ! -type d  -mtime +2 -exec rm -f {} \;
    



That's it!


quick server pages    
Copyright Steve Grubb    


Markup created by unroff 1.0,    April 28, 2004.