Introduction to startsite.pl script
The script 'startsite.pl' is located in the same directory where 'srvrun.pl' script is. It's a multipurpose wrapper that performs following tasks:
- initializes some environment variables to provide platform abstraction to the scripts - by computing various paths;
- checks whether the same site is already running on the computer - by loading state files and file containing port number web server for started for a given site last time; if it finds that the server for this site is already running, it just opens browser window with default site page and finishes execution.
- If no server is running for the site in question, a pair of free TCP ports is found, and configuration file with these port numbers and location of the document root is written in the temporary configuration file;
- Then Stunnix Perl Web Server itself is started by invoking 'srvrun.pl' script in the background, getting settings from 'httpd.conf' located in the directory where 'srvrun.pl' resides and from temporary configuration file generated on the previous step;
- Then 'startsite.pl' script waits till web server starts serving http requests;
- Once web server is listening for incomming connections, user's browser is started and default web page of the site is opened in it;
| Name | Default value | Description |
|---|---|---|
| _debug | 0 | Specifies whether debugging mode is On. When debugging mode is on, the trace of performed operation is written to stderr, and some temporary files are not deleted at the end of script execution. |
| _docroot_default | ../www/root | Specifies the directory that corresponds to the root of the site. It can be relative path (with directory containing 'srvrun.pl' being the base for it). It's highly recommended to use unix-style slashes as directory separators; trailing slash is mandatory. |
| sitename | default | Specifies the so-called site ID. It's a string that unqiuely distinguishes the site from others. It should contain version number too. No more than 1 web server process group can be serving site with the same site ID for the given user. Giving sites with different content different site IDs allows user to use these several sites simultaneously. |
| urlpath | Specifies the default URL path to open in the browser once web server is started for the site. Default value is empty string. It should start from slash if non-empty! | |
| show_win32_firewall_alert | 1 | Specifies whether to show message about possibility of firewall alerts on Windows platforms. Set to 1 to show it, set to 0 in order not to show it. |
| win32_firewall_alert_message | Specifies the message to show first time web server product is run on user's computer. If empty, fallback text is used. | |
| macosx_prefer_ie | 0 | Specifies whether to try opening page in MSIE if it's available (instead of default browser, that is Safari on most of MacOSX computers) on MacOS X. Set to 1 to try MSIE first, set to 0 to use default browser. |
| win32_prefer_ie | 0 | Specifies whether to try opening page in MSIE (instead of default browser). Set to 1 use MSIE, set to 0 to use default browser. |
| win32_msie_prop__addressbar, win32_msie_prop__menubar, win32_msie_prop__statusbar, win32_msie_prop__toolbar, win32_msie_prop__resizable, win32_msie_prop__silent, win32_msie_prop__fullscreen, win32_msie_prop__theatermode, win32_msie_prop__height, win32_msie_prop__left, win32_msie_prop__top, win32_msie_prop__width | Specifies the value of the corresponding MSIE window property. Documentation on the meaning of this properties can be found in MSDN documentation. Use these settings to e.g. disable statusbar or menubar in MSIE. These settings apply only if win32_prefer_ie=1 and win32_prefer_ie_kiosk_mode=0. Default value is empty string for each option, and this means that the MSIE-default value is used for the MSIE object property. Use 0 or 1 for boolean properties and integers for other properties. | |
| win32_prefer_ie_kiosk_mode | 0 | Specifies whether to try opening page in MSIE in kiosk (fullscreen) mode. If value is 1, value of win32_prefer_ie is ignored (i.e. value of win32_prefer_ie does not affect win32_prefer_ie_kiosk_mode at all) |
| nobrowser | 0 | Specifies whether not to open any browser at all. This is useful if you run some web services using SPWS and access them from your application, so that no browser window needs to be opened. |
| _debugtofile | 0 | Specifies whether log all stages of startup process (finding port number, copying database files, starting MySQL server and so on) to 'c:/spwstrace.txt' (on Windows) or '/tmp/spwstrace.txt' (Linux or MacOSX). |
| port_to_start_scanning_from | 9000 | Specifies whether log all stages of startup process (finding port number, copying database files, starting MySQL server and so on) to 'c:/spwstrace.txt' (on Windows) or '/tmp/spwstrace.txt' (Linux or MacOSX). |
| program_to_run_before_browser_M, program_to_run_after_browser_M, program_to_run_before_server_M |
M can be 1, 2 or 3.
Specifies the names of the programs to run before or after starting
the browser, or before running the server.
Up to 3 programs for running before and up to 3 programs
for running after can be specified. If value is empty string, the
program with given index is not run. It's possible to specify the
delay to perform (time to wait in seconds) after starting the program
using options program_to_run_before_browser_M_sleep_seconds
or program_to_run_after_browser_M_sleep_seconds
or program_to_run_before_server_M_sleep_seconds
(default time to wait is 0). Since /site/config/siteinfo.pm is effectively a Perl script, one can compute names of the programs depending on the OS version and so on, see sample file from democd or ask us for more information. Since it's possible to switch off starting browser using nobrowser option, it's possible to use interfaces not based on browser for running application (e.g. UI made as flash clip). The programs can retrieve the port number the server will listen on using SERVER_PORT environment variable; the fact whether web server was already running is passed using STUNNIX_WEBSERVER_WAS_ALREADY_RUNNING environment variable. All programs started using these settings will be automatically terminated on the server shutdown. The paths to the programs need to be relative to CD root. |
Altering behavior of 'startsite.pl'
Behavior of 'startsite.pl' script is rather configurable. Default values for configuration settings are stored in the %config hash, initialized in the script. It's possible to specify desired values for the settings using two methods:
- In the external file with name 'siteinfo.pm' located in the directory where 'startsite.pl' resides;
- In the external file with name 'siteinfo.pm' located in the directory "../config/" relative to the directory where 'startsite.pl' resides;
- By passing space-separated names and values of configuration settings on the 'startsite.pl' commandline;
Specifying settings in the external file
During execution of 'startsite.pl', the existance of file 'siteinfo.pm' is checked in the directory where 'startsite.pl' resides. If it exists, it's interpreted using 'do' statement. This script is supposed to modify values of %config hash in any meaningful way. Then the existance of "../config/siteinfo.pm" is checked and it's interpreted with 'do' statement too. It's greatly adviced to put all configuration settings to "../config/siteinfo.pm" rather than to "siteinfo.pm" residing in the directory where startsite.pl resides.
Here is a content of 'siteinfo.pm' from the sample site shipped with Stunnix Perl Web Server (it's located in /sample-image/site/stunnixwebsrv/ directory):
$config{_docroot_default} = '../www/root/';
$config{sitename} = "Perl-Obfus-2.0-Standard-0";
As you can see, the 'sitename' setting includes version of the browser-based
application to allow running several versions of browser-based applications
at the same time.
Specifying settings on the command line
It's possible to pass values of settings on the commandline of 'startsite.pl'. Just specify name and value pairs on the commandline, as in example below:
perl startsite.pl _debug 1 urlpath /admin.shtmlIn the example above, values of '_debug' and 'urlpath' settings were specified on the commandline.