quisp: setting up a web site

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!

- You are now all set to begin developing HTML files with QUISP markup using your favorite text editor. The files should reside in the `./pages` subdirectory.`` You can remove the test page and data files whenever you're ready to.``
- Data files can be placed in the `./data` directory (see the shsql tables manual page), or they can reside just about anywhere on your file system.``
  quick server pages
  Copyright Steve Grubb

Markup created by unroff 1.0, `` `` April 28, 2004.