.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
        OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }

        H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
        H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
        H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
        H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>quisp: setting up a web site</title>
<body bgcolor=99cc99 vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550 ><tr>
<td align=right><a href="quisp_home.html">
<img src="img/quisp2.gif" border=0><br><small>quick server pages</a> &nbsp; &nbsp; </td></tr>
<td>
.>>

.TH Setting up a web site TDH "28-APR-2004   TDH scg@jax.org" 

.SH 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.

.ig >>
<br><br>
.>>

.IP \(bu
.ig >>
<a href="support.html">
.>>
\0Install QUISP
.ig >>
</a>
.>>
if you haven't already done so.

.ig >>
<br><br>
.>>

.IP \(bu
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.

.ig >>
<br><br>
.>>

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

.ig >>
<br><br>
.>>

.IP \(bu
As this UID, run the shell script \fBnewproject.sh\fR (it's located in the \fC./bin\fR).
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.

.ig >>
<br><br>
.>>

.IP \(bu
Go into the new directory.
Edit the \fCconfig\fR file, and change the \fBdbbin\fR  entry from \fCpath\fR 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 \fCconfig\fR file.

.ig >>
<br><br>
.>>

.IP \(bu
Also in your \fCconfig\fR 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:
.nf
  varvalue:       HTMLURL=        
  varvalue:       HTMLPATH=/home/groups/q/qu/quisp/htdocs  
.fi


.ig >>
<br><br>
.>>
.IP \(bu
Set (and export) a shell environment variable called \fBSHSQL_DB\fR ...
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.

.ig >>
<br><br>
.>>

.IP \(bu
Determine if you are setting up a read-write, or read-only application.
.ig >>
<a href="security.html">
.>>
\0More discussion.
.ig >>
</a>
.>>
.ig >>
<br><br>
.>>

.IP \(bu
Copy the \fCquisp\fR 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 \fCquisp\fR.
More advanced users can name the executable anything desired, for example, \fCmydbcgi\fR, and
there can be multiple \fCquisp\fR 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
.ig >>
<a href="graphic.html#setup">
.>>
\0additional considerations.
.ig >>
</a>
.>>


.ig >>
<br><br>
.>>
If you're setting up a read-write application, the \fCquisp\fR
(and \fCquisp_pl\fR) executable should be \fBsetuid\fR to the owner of the project/database directory.
It should have a permissions mode of \fB6755\fR (\fC-rwsr-sr-x\fR); if it doesn't,
use a command like this: \fCchmod 6755 quisp  \fR 
(Note that some web hosts may have 
.ig >>
<a href="security.html">
.>>
\0restrictions on setuid CGI programs.)
.ig >>
</a>
.>>

.ig >>
<br><br>
.>>
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 \fC./tmp\fR (as is done with graphics) then \fC./tmp\fR will need to be world-writable.  
The \fC./logs\fR will need to be world-writable if you decide to capture error messages
or usage info.

.ig >>
<br><br>
.>>
.IP \(bu
Now go to your \fBcgi-bin\fR and make a soft link to your project \fCconfig\fR file (that was created by \fCnewproject.sh\fR).
The link should have the same name as the quisp executable (or link) that's in the cgi-bin, with \fC.cnf\fR appended to the end.
For example, for \fCquisp\fR name it \fCquisp.cnf\fR.  For \fCquisp_pl\fR name it \fCquisp_pl.cnf\fR.
If you renamed your quisp executables use the same name with a \fC.cnf\fR 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.
.ig >>
<a name=examples></a>
.>>

.ig >>
<br><br><br>
.>>

.SH Test drive 

After running \fCnewproject.sh\fR make sure things are working by accessing
some demo material that is automatically installed by \fCnewproject.sh\fR:


.IP \(bu
Try an SQL select command from the command line, eg:
.br
\fCshsql -n "select * from examp_people"\fR.

.ig >>
<br><br>
.>>

.IP \(bu
Try a test web page.  
Fire up your web browser and enter a URL that will invoke quisp, via your cgi-bin, eg:
.br
\fChttp://abc.com/cgi-bin/quisp\fR
.br
The specifics of this URL depend on your local system.
.br
If all goes well, QUISP should load a test page.
If not, use something like this:
.br
\fChttp://abc.com/cgi-bin/quisp?_DEBUG=1\fR
.br
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).


.ig >>
<br><br><br>
.>>

.SH More test examples

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

.ig >>
<br><br>
.>>

.IP \(bu
These examples can also be tried anytime from the
.ig >>
<a href="http://quisp.sourceforge.net/cgi-bin/quisp?rtn=index">
.>>
\0quisp web site on sourceforge.
.ig >>
</a>
.>>

.ig >>
<br><br><br>
.>>
.SH Finishing touches
Do these after achieving success on the test drive.

.IP \(bu
If you're generating graphics using quisp_pl, again edit your \fCconfig\fR file,
uncomment CGIPROG and CGIPROG_PL, and set them appropriately for your installation.
Here's what I use on the live demo on sourceforge:
.nf
  varvalue:       CGIPROG=/cgi-bin/quisp          
  varvalue:       CGIPROG_PL=/cgi-bin/quisp_pl    
.fi

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


.ig >>
<br><br><br>
.>>

.SH That's it!

.IP \(bu
You are now all set to begin 
.ig >>
<a href="quisp_home.html">
.>>
\0developing HTML files with QUISP markup
.ig >>
</a>
.>>
using your favorite text editor.  
The files should reside in the \fC./pages\fR subdirectory.
You can remove the test page and data files whenever you're ready to.

.ig >>
<br><br>
.>>

.IP \(bu
Data files can be placed in the \fC./data\fR directory (see the 
.ig >>
<a href="../../sqlman/html/tables.html">
.>>
\0shsql tables manual page),
.ig >>
</a>
.>>
or they can reside
.ig >>
<a href="../../sqlman/html/ordfiles.html">
.>>
\0just about anywhere
.ig >>
</a>
.>>
on your file system.

.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="quisp_home.html">
<img src="img/quisp2.gif" border=0></a><br>
<small>quick server pages &nbsp; &nbsp;<br>
<a href="Copyright.html">Copyright Steve Grubb</a> &nbsp; &nbsp;
</td></tr>
</table>
.>>

