Copyright: Copyright (c) 1995-1998 HREF Tools Corp.


Installation Help

WebHub is designed to work with all popular web servers on the Windows NT platform.  This help file discusses your installation decisions so that you can quickly start using the full power of WebHub with your web server.

Overview of WebHub installation

• What's being installing on my system?

———————————————————————

Question 1: Location of HREF Tools Directory

• Pro's and Con's of using the default c:\ht location

Question 2: Location of public HTML and graphics files

• Pro's and Con's of using the default c:\htdocs location

• What to do if you've already installed to the default location

Question 3 a-b-c: Location of Runners

• Pro's and Con's of using the default runner locations.

 ———————————————————————

Wait - I don't have a web server software installed yet!

• Where to get web server software

I'm UPGRADING a previous WebHub installation- what's the best approach?

• How to upgrade most easily

What Next?

• How to Confirm Your Web Server Sortware Setup

• Installing VCL Components

Notes about Popular Web Server Software

•  O'Reilly's WebSite Server

•  Microsoft IIS

•  Microsoft Personal Web Server

•  Netscape Web Servers

•  Alibaba Web Server

•  Other

FYI: Installation Trivia

• Demo Project Adjustment

• Program Shortcuts

• Documentation

• Graphics

• Context-Sensitive Help for VCL Programmers

• Uninstall

HREF Tools Corp.

• Contact Info

Copyright (c) 1997-1998, HREF Tools Corp. All Rights Reserved Worldwide.

Last updated 27 October 1998.  Free updates for this file are available at: http://www.href.com/pub/docsnhelp


Installation Overview
Overview of WebHub Installation

Installing WebHub on your system will add the following types of files to your computer:

• WebHub Delphi VCL components which will add functionality to your development environment.

• WebHub runners (both ISAPI and cgi) to facilitate communication between your applications and your web server software.

• Full product documentation and help files.

• Source code for a variety of demonostration projects.

• HTML files and graphics associated with the demonstration projects.


Downloading a Web Server
Obtaining a Web Server

WebSite from O'Reilly and Associates will run on Windows 95 and NT.  It is easy to use and includes good documentation.  WebSite 1.1e is free for non-commercial use.  O'Reilly is now promoting version 2/Pro but you may download version 1.1e from ftp://href.com/OReillyWebSite/.  WebSite 1.13 is included on the WebHub CD under 3rdparty products.

Microsoft NT server includes a free web server called IIS, Internet Information Server.  It is part of the NT Option Pack.

Microsoft has another web server for use on Windows NT Workstation and Windows 95, called Personal Web Server, which you can download from http://www.microsoft.com.  Note! Personal Web Server running under Windows 95 is not compatible with WebHub v1.276 through 1.49.  Personal Web Server can be used with WebHub under Windows NT Workstation, though the 10 concurrent user connection limit imposed by NT Workstation make this combination suitable for development or low traffic web sites only.  Future versions of WebHub may support PWS running under Windows 95.

Netscape also has web servers available on a free trial basis from http://www.netscape.com.


How to Upgrade Most Easily

• If you are using a DLL runner (e.g. ISAPI runisa.dll), be sure to stop your web server so that the DLL is unloaded out of memory. Otherwise a new copy will not be installed.

• If you are a VCL programmer, be sure that Delphi is closed. Otherwise the wizard cannot be installed.

• Rename your ht\ directory to anything else.  This gives you an easy backup and also clears the way for the new files.  If you were to install the WebHub VCL on top of existing files, you would be very likely to have problems. By renaming the ht\ directory you ensure that new components are install into an empty ht\lib32 directory.

• Backup or rename your htdocs\ directory if you made any important changes to the demos or the graphics.

• Manually create a replacement ht\ directory and then COPY your hubmain.ini file to ht\hubmain.ini.  This will preserve all your custom AppID definitions. If you haven't made any custom applications, disregard this step.

• Install as usual into the mostly-empty ht\ directory.

• If applicable, move your own subdirs back under the new ht\ directory.

• If in doubt, make a complete backup of your ht\ and htdocs\ directories.

• If there are any technical issues that you need to know for upgrading, they will be listed in the Release Notes files which are kept at http://www.href.com/pub/relnotes/.  If you have the WebHub CD, you will find the release notes in the ERRATA directory.


HREF Tools Software Directory

Reasons to Use the Default c:\ht Directory

1. Your setup will exactly match all the documentation, and any conversations for tech support will be based on a "standard" setup.

2. If you are a Delphi programmer, the path to the VCL components will be fairly short.  Since there is a fixed size limit to certain component search paths, this is a consideration.

3. ht\ is a nice short phrase to type.

Reasons Not To

1. You like installing all software under \Program Files\.

2. You don't have permission to create a new directory in c:\.

3. You can think of an alternative installation path that's easier for you to remember.

A Non-Default Directory is Ok!

All the features and demos should work perfectly fine regardless of what directory path you choose. There are no limitations as to drive letter, path name, or the use of spaces in paths.

Delphi programmers note: the installation will adjust the contents of the demo .dpr files to make use of your chosen installation path.  If you want to change paths *after* installing, run the ht\htUtil\AdjDpr.exe utility to fix up all the DPRs.


What to do if you've already installed to the default location

... and the demos have broken links or broken graphics...

Option 1. Copy/Move the "htdocs" files

Move the 3 subdirectories from c:\htdocs\ to wherever your web server's public HTML area is.

For example, for Microsoft IIS, move c:\htdocs\htdemo\*.* to c:\inetpub\wwwroot\htdemo.  For Microsoft PWS, move c:\htdocs\htdemo\*.* to c:\wwwroot\htdemo.  For O'Reilly's WebSite, move c:\htdocs\htdemo\*.* to c:\website\htdocs\htdemo\*.*.

Option 2. Set up 3 directory mappings

Add directory mappings to your web server so that it knows what /htdemo/, /htsysmsg/ and /planet/ should resolve to.

For example, map /htdemo/ to c:\htdocs\htdemo\.

Background on Graphics

The web server is in charge of displaying graphics, such as those requested thought an <IMG SRC> tag.  By default, the web server will look for graphics beneath the web server "root" directory.  However, by adding "mappings" you can change the rules so that files are retrieved from entirely different places.

To make the graphics show up in all the demos, your web server needs to know where to find files for /htdemo, /htsysmsg and /planet.


Displaying Graphics
Public HTML and Graphics Root Directory

The WebHub System includes a few files that need to be installed in a directory which the web server can find.  In addition, the WebHub demos include dozens of files which are meant to be displayed over the web.  For this reason, during the WebHub installation you are given a choice as to where you want to install these files.  The trick is to coordinate the target WebHub installation directory with that of your web server.

Pro's of using the c:\htdocs default

1. Your installation will match all the documentation.

2. If you are testing multiple web servers on the same machine, it's handy to have all the files in a neutral place, outside of any one web server's "territory."

Con's of using the c:\htdocs default

1. You will need to add 3 directory mappings to your web server setup, for /htdemo, /planet and /htsysmsg.  For example, map /htdemo/ to c:\htdocs\htdemo.

If this doesn't sound easy, you should figure out the "root" for your web server and enter that path instead of c:\htdocs.  Then the WebHub files will install into a place that will immediately integrate with your web server.

Example:

for Microsoft IIS, use c:\Inetpub\wwwroot\ as the root.

for Microsoft PWS, use c:\wwwroot\ as the root.

for O'Reilly WebSite, use c:\website\htdocs\ as the root.

If you change your mind after installation, that's ok.  Just move the files or add a mapping.


Runners
WebHub Runners

WebHub includes a "runner" for each popular Windows web server interface.  The runner is the program that the web server will call when a dynamic page request comes in.

•  runwin.exe for cgi-win, installed to c:\ht\htexe\cgiwin\

•  runbin.exe for cgi-bin, installed to c:\ht\htexe\cgibin\

•  runisa.dll for ISAPI, installed to c:\ht\htexe\isapi\

•  runnsa.dll for NSAPI (not shipping as of v1.50)

Pro's of Using the Default Runner Locations

1.  Your setup will match all the documentation.

Con's

1.  You will need to add a web server mapping so that your web server can find the runner.  If that sounds difficult, you should instead install the runner to the CGI or ISAPI area for your web server.  This depends entirely on your web server and how it has been configured.  Defaults are listed below.  If you are not sure, use the default location and later copy the runner to the required directory.

Likely CGI or ISAPI areas by Web Server

Web Server	Path	Runner Type
Microsoft IIS	c:\inetpub\scripts\	ISAPI (runisa.dll)
Microsoft PWS	c:\scripts\	ISAPI (runisa.dll)
O'Reilly WebSite	c:\website\cgi-win\	cgi-win (runwin.exe)
Netscape (various)	c:\??\cgi-bin\	cgi-bin (runbin.exe)
Note for people upgrading and using the ISAPI runner

Make sure you stop the web server so that the runner is unloaded before you install. Otherwise the runner file may be in use and will not be installed/upgraded at all.

Important note regarding directory permissions

In order for the WebHub runner to be accessible to users, the directory in which the runner is placed must have execute rights enabled.  Your web server software will only respond to requests from the runner if the anonymous Internet user has been granted the appropriate permissions. If you have a file execute permission problem you will see the following type of error in your browser:  HTTP/1.0 403 Access Forbidden (Execute Access Denied - This Virtual Directory does not allow objects to be executed.)

To verify permissions:

- Start the WindowsNT Explorer

- Locate the directory containing the WebHub Runner

- Right-click on the director and select "Properties"

- Select the "Security" tab

- Press the "Permission" button

- Make sure the Internet Guest Account has both Read(R) and Execute(X) permissions


IIS Installation Notes

Where to get a copy

Microsoft Internet Information Server (IIS) is included with NT 4 server. The latest version is generally posted on their web site at:

http://www.microsoft.com/windows/downloads/contents/Products/NT4OptPk/default.asp.

How to Administer

IIS Version 2, Internet Service Manager

Run the Internet Service Manager. You will find this under Programs|Microsoft Internet Server.

WebHubDemo Graphics

Directory Mappings in IIS

WebHub Runner

Use the WebHub ISAPI runner which is named runisa.dll. Copy c:\ht\htexe\runisa.dll to your scripts directory, or add a directory mapping to c:\ht\htexe\isapi\.

Make sure your script directory is tagged to allow Execute.

WebHub Graphics

Add mappings for /htdemo as shown above. This will enable you to see all the graphics in the WebHub demos.  NB: even though they are shown in this picture, it is not necessary to change the <Home> directory, nor is it necessary to change the default document to index.htm.


Personal Web Server Installation

Download

http://www.microsoft.com/windows/downloads/contents/Products/NT4OptPk/default.asp

Install

Microsoft's Active Setup program will guide you through the download and installation of the product.

How to Administer

Personal Web Server 4.0 is controlled through the Microsoft Management Console that is opened by choosing "Internet Service Manager" from the Start menu.  The console permits server, website and file specific settings that give a good degree of control over behavior of the web server.  The console allows creation of new "virtual directories" that can be pointed at the default file location for the WebHub runners and graphic files:

Directory Mappings in IIS

WebHub Runner

Use the WebHub ISAPI runner which is named runisa.dll. Copy c:\ht\htexe\runisa.dll to your scripts directory, or add a directory mapping to c:\ht\htexe\isapi\.

Make sure your script directory is tagged to allow Execute.

WebHub Graphics

 Add mappings /htdemo as shown above. This will enable you to see all the graphics in the WebHub demos.  NB: even though they are shown in this picture, it is not necessary to change the <Home> directory, nor is it necessary to change the default document to index.htm.

Confirm that the Web Server is Running

Use your web browser to request

http://localhost/

or

http://127.0.0.1/

to test your web server installation. If you have a domain name or know your IP number, of course you can also use that for testing.

The web server should respond with something when you do this.  If not, consult your web server documentation.

Confirm WebHub Demos Installation

http://localhost/htdemo/index.htm

That should give you a static test page like the following, which will lead you through a series of tests that let you completely confirm your installation and start working with the demos.


WebSite Installation Notes

Download

ftp://href.com/OReillyWebSite/

WebSite 1.1e is also included on the WebHub CD from HREF, under 3rdParty products. We ship this web server because it runs on Win95, NT workstation and server and has a good user interface for administration.

Other versions of WebSite

If you want to do secure transactions, be sure to look at WebSite Professional.

Otherwise we recommend that you buy the $59 book + WebSite 1.1e combination from O'Reilly and Associates, http://website.oreilly.com.


WebSite: Web Root

The default directory c:\website\htdocs\ is fine.


WebSite: Server Run Mode

Beginners should run WebSite as an Application, manual start. It will be visible in the tray and you can start, pause, resume, and stop the server by clicking its icon directly.


WebSite: Host Domain Name
WebSite: Host's Domain Name

  Use 127.0.01 if you are not sure of your IP# or your domain name.

Example: www.href.com
Example: 123.123.123.321


WebSite: E-Mail Address

  It is ok to leave this blank; you can fill it in later.

Example: techsupport@href.com
Example: webmaster@yourcompany.com


WebSite: Server Admin
WebSite: Server Administration

Once you have WebSite running, you can review and change any of your settings. Click on the website icon, and choose Properties from the menu. That brings up this screen. Settings should be similar on your system.


WebSite: cgi-win mapping

If you are on Win95, you should use the cgi-win runner named runwin.exe. Notice the List Selector is on Windows CGI.

/cgi-win/ is mapped to c:\ht\htexe\cgiwin\. Enter exactly as shown here.


WebSite: cgi-bin mapping

If you are on NT and want to use WebSite, we recommend the cgi-bin runner for most people. (cgi-win is still better at file uploads.)  Note the List Selector is on Standard CGI (that means cgi-bin).

/cgi-bin/ is mapped to c:\ht\htexe\cgibin\.


WebSite: graphics mapping
WebSite: Graphics

To see the graphics used in the demos, you need one more directory mapping for htdocs\htdemo\.

/htdemo/ is mapped to c:\htdocs\htdemo\.


Netscape Installation Notes

Installation Notes

Use all the defaults, and change them after installation is complete. Using pre-existing directories other than the defaults can crash the installation program.

How to Administer

Use the Administer Netscape Servers icon to start its admin program. This runs through your web browser, so you can use it remotely. Remember your login name and password!

Runner Configuration

To set up cgi-bin for use with WebHub, click on [Programs] along the top menu bar. Then click [CGI Directory] on the left side. Set:

URL Prefix:             cgi-bin/
CGI directory:          location of runbin.exe runner, e.g. c:\ht\htexe\cgibin


Alibaba Web Server Tips

Download

http://alibaba.austria.eu.net/

This web server is recommended if you want to learn about SSL (secure sockets layer) and want free security certificates to practice with.

Use the cgi-bin runner.


Other Web Servers

Runner and Graphics Configuration

Use the cgi-bin runner.

Move the \htdocs\htdemo\ directory under your "web root" instead of under \htdocs\.  Copy the ht\htexe\cgibin\runbin.exe runner to the cgi-bin directory for your server.


Setting MIME Types
What are MIME types?

In order for your web server software to include graphics and other multimedia components in your web pages, they must be stored and delivered in a format that is recognized by both the web server and the client browser.  Acceptable formats are stored in lists of MIME (Multipurpose Internet Mail Extension) types that is managed on both the server and client side of the connection.

Most common multimedia files will already be configured for proper delivery by your application, but there may be situations where you wish to serve additional MIME types that will need to be added to the list of recognized formats.

Configuring Server MIME types with Internet Information Server/Personal Web Server


Confirming the Web Server Installation

Confirm that the Web Server is Running

Use your web browser to request

http://localhost/

or

http://127.0.0.1/

to test your web server installation. If you have a domain name or know your IP number, of course you can also use that for testing.

The web server should respond with something when you do this.  If not, consult your web server documentation.

Confirm WebHub Demos Installation

http://localhost/htdemo/index.htm

That should give you a static test page, which will lead you through a series of tests that let you completely confirm your installation and start working with the demos.

If you can not load the demo index page, read this!


Contact Info
HREF Tools Corp. Contact Info

Technical support:	http://www.href.com/techhelp/

WebHub Discussions

by E-Mail:	http://www.href.com/listserv/

Catalog by

EMail:	mailto:catalog@mail.href.com

Sales thru Zac:      	http://www.zaccatalog.com

Sales thru HREF:	http://www.href.com

HREF Tools Corp.

300 B Street

Santa Rosa, CA 95401

U.S.A.

tel: 707-542-0844

fax: 707-542-0896


Demo Project Adjustment

This applies if you install the WebHub VCL Developer Bundle.

At the end of the installation, you may notice a DOS window open and see some text flash by. This is the ht\htutil\adjdpr.exe utility running.  It adjusts the demo .dpr files to use the path you selected during installation.  This lets you install to any location and still easily open all the demo projects.


Program Shortcuts

After installing the software, you will have a shortcut under Programs|HREF Tools with a link to:

WebHub Central ("The Hub")  ht\htexe\hub.exe

If you installed WebHub Power HTML, you will also have a link to the WebHub Application Server.

You will also have links to appropriate documentation files, such as the User Manual and help files.


Documentation

WebHub documentation is installed to the ht\doc directory.  For people who do not have the printed manual -- you will need the free Adobe Acrobat Reader to open the PDF files which you may download from this URL:

http://www.adobe.com/prodindex/acrobat/readstep.html


Graphics

The default graphics file format for the demos is the JPG file format.  Unisys is requesting expensive license agreements for the use of the GIF file format and the PNG file format is subject to browser incompatibilities, so we have use JPG instead.


Context-Sensitive Help for VCL Programmers

Delphi 2 and 3 handle help in different ways.

For Delphi 2, we provide the webhub.hlp and webhub.kwf files. Use Borland's HELPINST utility to integrate these files into Delphi's help system.

For Delphi 3, the installation procedure does three things to make sure you automatically get context-sensitive help on the components.  It deletes your delphi3.gid file (which Delphi will rebuild when you request help), edits the delphi3.cfg file to add a link to webhub.hlp, and modifies the registry to point to the webhub.hlp file.

Under Delphi 3, WebHub help topics will appear as if they are part of the Delphi help system, and clicking on [Contents] will take you to the Borland help contents.  That won't help you if you are looking for a topic such as WebHub macros!  So keep reading ...

To get to those non-component topics, you need to reach the WebHub Contents page.  To do that, open webhub.hlp directly.  The easiest way is to use the shortcut under Programs|HREF Tools|WebHub Help.


Installing VCL Components

This topic is covered in the regular WebHub Help File.

Start Programs|HREF Tools|WebHub Help File.


Uninstall
Uninstalling WebHub from a Machine

Use the uninstall option, or just erase these directories:

ht\*.*

htdocs\htdemo\*.*

htdocs\htsysmsg\*.*

htdocs\planet\*.*

Delete your WebHub runner if you copied it outside the ht\ directory tree, e.g. delete c:\InetPub\scripts\runisa.dll.

To remove the WebHub VCL packages, do this:

• Launch Delphi

• Project|Options|  Packages Tab

• Select HREF Tools Webhub and TPack Components, click REMOVE then Yes.

• Repeat for any remaining HREF Tools packages.

• Exit Delphi