#set TITLE = "Setting up a web site"
#include top

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

#include space2

.IP \(bu
#set FILE = "support.html"
#set TAG = "Install QUISP"
#include link
if you haven't already done so.

#include space2 

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

#include space2

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

#include space2

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

#include space2

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

#include space2

.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


#include space2
.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.

#include space2

.IP \(bu
Determine if you are setting up a read-write, or read-only application.
#set FILE = "security.html"
#set TAG = "More discussion."
#include link
#include space2

.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
#set FILE = "graphic.html#setup"
#set TAG = "additional considerations."
#include link


#include space2
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 
#set FILE = "security.html"
#set TAG = "restrictions on setuid CGI programs.)"
#include link

#include space2
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.

#include space2
.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>
.>>

#include space

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

#include space2

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


#include space

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

#include space2

.IP \(bu
These examples can also be tried anytime from the
#set FILE = "http://quisp.sourceforge.net/cgi-bin/quisp?rtn=index"
#set TAG = "quisp web site on sourceforge."
#include link

#include space
.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

#include space2
.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


#include space

.SH That's it!

.IP \(bu
You are now all set to begin 
#set FILE = "quisp_home.html"
#set TAG = "developing HTML files with QUISP markup" 
#include link
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.

#include space2

.IP \(bu
Data files can be placed in the \fC./data\fR directory (see the 
#set FILE = "../../sqlman/html/tables.html"
#set TAG = "shsql tables manual page),"
#include link
or they can reside
#set FILE = "../../sqlman/html/ordfiles.html"
#set TAG = "just about anywhere"
#include link
on your file system.

#include bottom

