|Installing WebSiphon 2|
After you have verified that your server hardware meets WebSiphon's humble system requirements, begin the installation process by obtaining the current release of WebSiphon from the Purity web site.
The WebSiphon 2 Package
After downloading and decompressing the download, you should have a folder which looks similar to:
figure: WS2 download package contents.
By installing and using WebSiphon 2, you agree to be bound by the terms of our licensing which are outlined in the "License Agreement" file included in the distribution. If you have any questions about the agreement, or wish to offer a suggestion of improvement, please contact Purity Software directly.
The "Version History" file provides a glimpse into the many stages of evolution which has led to the current incarnation, including changes applied to the most recent release.
Choose an Installation Type
WebSiphon 2 supports two different types of installations:
- an external ACGI application; or
- an W*API-compliant plug-in library.
There are features and limitations unique to each installation type which should be considered:
- the ACGI runs as an external process, with its own memory space; whereas the plug-in version is loaded as part of the web server process, and shares memory space with the web server and any other installed server plug-ins.
- the plug-in version is significantly faster in operation than the ACGI application, as there is no overhead introduced by need for inter-process communication (via Apple Events) required between the web server and WebSiphon with each request.
- as an external process, the ACGI can be scripted to restart the web server remotely or execute other scripts arbitrarily if for some reason the web server process itself has failed; however, the plug-in cannot escape the grips of failure if the web server process fails.
- the ACGI version can accept incoming requests from Apple Script, Frontier or other environments which support Apple Events; the plug-in cannot receive event messages directly.
- in most cases the ACGI version will not work with POST arguments and HTTP file uploads beyond 32k in size (actually, a bit less due to variable data in the HTTP request and the overhead imposed by the Apple Event messenging architecture itself), due to lack of current support from most web server brands.
If your server supports it, the WebSiphon ACGI can receive large POST arguments using multiple ReadHTTPData events to read the request data in chunks and overcome any size limitations; the plug-in version does not suffer from arbitrary size contraints in working with POST data.
In most launch scenarios and if your server supports W*API, we recommend using the plug-in version. The speed gained by embedding WebSiphon as a plug-in library, coupled with able choice in using core features like file upload without limitations in your applications, provides an ideal web development platform.
However, WebSiphon is also quite capable as an external ACGI application and it shouldn't be discarded as an inferior configuration. In some integration scenarios the unique benefits offered by the external application outweigh those offered by the plug-in. Choice is good.
Copy Files to the Server
Once you have decided on an installation path, the time has come to copy the required runtime binary and supporting data files to the web server:
- ACGI Installation
- Copy both the "WebSiphon.acgi" application and the "WebSiphon Data" folder into the web server's "cgi-bin" directory.
- W*API Plug-in Installation
- Copy the "WebSiphon Plug-in" library and the "WebSiphon Data" folder into the web server's "Plug-ins" directory. Both of the "WSThreadsHub" and "MSL_All_PPC.Shlb" support libraries should be placed (copied) in the same directory as the web server application itself.
The "WSThreadsHub" and "MSL_All_PPC.Shlb" support libraries are only required by the plug-in installation, and as such they are ignored by the ACGI application if present.
Although it is technically possible to run both the ACGI and plug-in at the same time, this is not a "supported" system configuration. With that said if you choose to consider this route, it is important that each installation's "WebSiphon Data" folder is properly encapsulated and kept separate from the other.
Secure all WebSiphon Data Files
There are a few installation-related security considerations which require attention prior to continuing:
- Secure the "WebSiphon Data" folder
- Define a security realm and any other barriers necessary to insure that it is impossible to access files within the "WebSiphon Data" folder using any network service enabled on the web server. This includes FTP, AFP, or any other service.
WebSiphon and installed add-on libraries use this directory as a general repository for core environment settings and other preferences data, including private data like your serial registration key, the global data file, and Verona database tables.
For specific descriptions of each of the supporting files which ship with the default WebSiphon 2 package, see the Support Files section below.
- Secure the "/pi_admin.ws" script
- Define a security realm to insure that only admin users can access WebSiphon's web-based administration script. It is located in the main "Templates" folder, and is completely customizable as the implementation is written in SiphonScript.
Before you choose to continue with configuring your WebSiphon installation without first applying the above protections to your server, consider that any user connected to the hosting network (in most cases, the entire Internet) could potentially download your serial number or other private data. Depending on your hosting scenario and visibility this could be viewed as a vulnerability or benign detail. Above all else, use and exercise appropriate judgment with this knowledge in making this assessment.
Runtime Licensing Options
WebSiphon will operate for a specified period of time, depending on the which runtime licensing option is utilized:
- 2-Hour Demonstration
- by default and without configuration, the demonstration mode allows processing requests using WebSiphon for two hours at a given time. After two hours, any requests will return a runtime error indicating the demonstration period has lapsed.
- 30-Day Evaluation Key
- a 30-day demonstration key may be obtained from the Purity web site which extends the default runtime period.
- Extended Runtime Key
- If you require a more creative approach to licensing in order to complete your development goals, please contact Purity directly for assistance. Extended development keys are available for projects which require an arbitrarily defined usage license.
- Permanent Owner Key
- If you have already purchased a permanent WebSiphon license, we extend a gracious and most sincere "Thank you" for your support! Your permanent owner serial key was sent to you along with the details of the order transaction.
If you haven't yet purchased WebSiphon, please consider (not later, impulse decisions are best) buying a copy or three! Not only does your purchase vote your interest and support for independent software -- it'll make our day; and we really enjoy food and a drink from time to time!
- Non-Commercial Application Key
- If you are using WebSiphon to develop and/or host a non-commercial application, you may be elegible for a free permanent license key to support your project. See the Purity web site for details on obtaining a non-commercial owner license.
Registering a Serial Key
When the WebSiphon environment is initialized without a valid serial key installed, the server will beep and automatically enter the 2-hour demonstration mode. Once you have obtained a serial key, whether it be temporary or permanent, it must be installed to enable an extended runtime period.
There are three different methods of configuring WebSiphon's runtime settings, each of which allow serial key registration:
- Using the ACGI application
- Choose "Register..." available under the Edit menu to register a serial key.
WebSiphon's core environment preferences and add-on library preferences are configured using their respective commands also available under the Edit menu. Some library settings such as those which manage secured and automated server authentications in CommerceLib, FileMakerLib, and VeronaLib inherently must be configured using the WebSiphon ACGI application over other methods.
- Using the web-based admin
- Connect to /pi_admin.ws to enter a serial key or manage WebSiphon's core environment preferences, as well as preferences for select add-on libraries (given special exceptions outlined above; see note in ACGI section).
- Manually, using a text editor
- Located in the "WebSiphon Data" folder, the "WebSiphon Prefs" file is a text file which may be edited manually using any standard text editor. It is important the file format integrity is maintained, and edits shouldn't be applied while the WebSiphon process is active. It is also not a good idea to edit this file unless you know what you are doing.
For further information on all available WebSiphon preferences, they are covered in detail in the Prefs section of the documentation.
Configuring the Web Server
The web server must be informed of what types of requests should be routed to, and thus processed by WebSiphon. This is done by defining a web server action which points to either the ACGI or plug-in, and then assigning specific triggers (such as a particular suffix mapping, or a special runtime request like an error or no access condition) which invoke the action. This process is only slightly different with each installation type.
The following instructions are generalized and apply to most server brands:
- Using the ACGI application
- Define an action named "SIPHON_CGI" (or something of your choosing which identifies WebSiphon as the target) whose path points to the location of the "WebSiphon.acgi" application. For most server installations this will be "cgi-bin:WebSiphon.acgi"; or perhaps the same with "/" instead of colon characters in the path string.
Next, define a suffix mapping which triggers the SIPHON_CGI action. The traditional convention for scripts written to be processed with WebSiphon is to use ".ws" to identify scripts and ".t" for substitution templates. Regardless of which suffix mapping triggers you choose, the default file type should be set as "TEXT", file creator set to the wildcard "*" character, and "text/html" as the MIME type.
- Using the W*API plug-in
- When you install the plug-in version of WebSiphon, the file suffix mapping ".ws" is automatically defined for you and assigned to the SIPHON_PI plug-in action. Additional suffix mapping triggers are defined as described in the ACGI section above.
For specific instructions on configuring WebSiphon for use with a specific server brand, see:
Serving with WebSiphon
If you have defined the suffix mapping ".ws" to be processed by WebSiphon, the request /mantis/test.ws will return the runtime output of the script named in the URL.
The actual "test.ws" file may exist in either of two locations on disk:
- at the web location /mantis/test.ws; or
- in the "WebSiphon Data:Templates" folder
The script which is run (executed) by WebSiphon is located according to a standard and logically defined file-finding algorithm.
Ready to find out more about using WebSiphon?
- move along to the Getting Started section to learn more about using WebSiphon; or
- continue with further details about configuring WebSiphon's various runtime and built-in library settings in the Prefs section.
To upgrade from WebSiphon v1.5.1 or later:
- The WebSiphon process should not be active while performing the upgrade process. If you're using the W*API plug-in version, you'll need to quit the parent server application to disable WebSiphon, otherwise simply quit the ACGI application and disable incoming events from the server.
- The "WebSiphon Data" folder contains all of your runtime and library settings, logs, database tables, and other private data. While the WebSiphon process is not active, rename your existing "WebSiphon Data" folder to "wsdata2003-10-27.bkup" or something else which you'll recognize. Test for validity, and once a known-good copy is achieved then archive the backup prior to continuing with the upgrade procedure.
- Copy the current release of WebSiphon, and its associated "WebSiphon Data" folder to the web server. A verbose guide to the installation procedure is offered above, in Installing WebSiphon 2.
- Now copy the following items to the new "WebSiphon Data" folder you just installed, using pre-existing backup data which was archived in step 2:
- the "WebSiphon Prefs" file, "Global Data" file, and "WebSiphon.log" file;
- any third-party or other custom add-on libraries or script libraries;
- the contents of the "Library Data" folder;
- any custom scripts from the "Templates", "Startup" and "Shutdown" folders.
- All scripts and templates written to work with previous versions of WebSiphon should function without modification when using the most current release. Read the version history for notes of change in behavior compared to previous releases.
WebSiphon stores all of its support files and runtime settings within the "WebSiphon Data" folder. By consolidating all environment data to a unified location relative to the WebSiphon process itself, it is possible to:
- backup all WebSiphon-related data with a single folder copy
- move environment settings from one server to another
- install new servers using custom-configured environment settings to maintain consistency across multiple servers
- install multiple, independent WebSiphon runtimes on a single computer (though this is an unsupported configuration, it is technically possible)
Full paths to each of the support folders are available as built-in variables. Using these built-in variables your scripts can store data using these same shared repositories.
Contents of the "WebSiphon Data" folder:
- "Global Data" file
- This file provides persistant, on-disk storage for global variables. It is safe to perform backups or to copy data between servers while the WebSiphon process is active.
- "WebSiphon Prefs" file
- This specially-formatted text file stores all of WebSiphon's core configuration settings, as well as that of some installed add-on libraries. It is important the file format integrity is maintained, and edits shouldn't be applied while the WebSiphon process is active. It is also not a good idea to edit this file unless you know what you are doing.
- "WebSiphon.log" file
- The main console output log saved to disk as a plain text file. The format of each line in the file is DATETIME\tLOG_EVENT_STRING\r. Log strings include startup messages, requested scripts, errors and other environment runtime events. The built-in function appendLog() also directs output to this file, if logging is enabled.
To disable logging, turn it off using the main Preferences panel, the web-based admin, or by directly editing the "WebSiphon Prefs" file while WebSiphon is not running.. Output will continue to the main console, but not be written to the file on disk.
- "Templates" folder
- This directory is used to hold scripts which may be accessed globally across the WebSiphon runtime environment. This includes all public web locations, virtual hosts, etc.
This folder is quite useful as a storage repository for standard templates (such as HTML headers, footers, or other display components) and custom libraries or other environment runtime extensions.
As an example, the web-based administration script is located in this directory. By default this script application has a ".ws" extension. Change the file suffix as needed to match your server settings or remove complete to disable entirely.
Regular user/developers should not have access to the "Templates" folder. From a security perspective, scripts which run from within this directory have root privileges and can modify the WebSiphon environment transparently and unequivocally.
- "Startup" folder
- Scripts in this folder will be executed immediately and only after the WebSiphon runtime environment is initialized. Common uses for startup scripts include custom scheduling or other initialization tasks which should execute each time the server starts up.
- "Shutdown" folder
- The opposite of the previous class, scripts in this folder will be executed prior to quitting the WebSiphon process. Uses for shutdown scripts include management of redundant arrays of independent servers, writing out buffered data, or other scenario-specific cleanup tasks necessary at shutdown.
- "Libraries" folder
- This folder contains both built-in libraries and script libraries, which are loaded during initialization of the WebSiphon runtime environment. Subfolders are recursively searched, and any file or folder with the name "(disabled)" in its path is ignored.
- "Library Data" folder
- Libraries and scripts may use this folder as a common repository to store and/or share data such as preferences, log files, or database tables.
contents prev nextCopyright (c)1996-2003 Purity Software