Bootstrap Scenarios

General Bootstrap operation

Bootstrap depends upon the %ENV{} variables to figure out where it is running from, and uses them to auto-configure Foswiki. It runs in two phases:

• Phase 1 runs during the Foswiki.pm BEGIN block and establishes all of the non-web-dependent settings. It merges in all the defaults from the Foswiki.spec and other Config.spec files. If Foswiki is being run from the CLI environment, bootstrap stops there.
• Phase 2 runs early in Foswiki::new() initialization, immediately after the Foswiki::Request object has been created. It uses the parsed URI and query information to bootstrap the web related settings.

Bootstrap phase 1

Phase 1 performs the following steps

• Attempts to locate the "root" of the Foswiki install by using FindBin to locate the directory containing the current script name. (This doesn't work on mod_perl)
  • For mod_perl, set the Environment variable FOSWIKI_SCRIPTS pointing to the Foswiki bin directory.
• Uses the script name to set the script suffix (e.g. .pl ) might need some adjustment for mod_perl
• Sets and validates all of the other *Dir locations relative to the bin directory. ( DataDir, PubDir, LocalesDir, ToolsDir, WorkingDir, TemplateDir and ScriptDir )
• Bootstraps the Store settings:
  • Searches for all *StoreContrib modules, and asks each if it can('bootstrapStore')
  • For each store with a bootstrapStore method, calls it to allow it to establish defaults. Note that the order of the Store bootstrap calls is not predictable, so each store needs to establish its settings, and then determine if it should override, or allow override by other stores. The current behaviour is that in absence of any conflicting history, Foswiki will default to the PlainFileStore.
    • RCSStoreContrib: Examines the DataDir and PubDir directories. If it finds that both ,pvf and ,v exist, then it dies, Foswiki is not usable with mixed store histories. If it finds any ,pfv directories, then it warns that it will not be usable because of existing revision history from the PlainFileStoreContrib. If it's usable, then it defaults to RcsLite, which is more universally compatible. If a Store has already been configured, RCSStoreContrib does not override the store.
    • PlainFileStoreContrib: Performs the same checks as RCSStoreContrib. If it does not find any conflicting revision history, then it sets the store to PlainFileStore. This does override the RCS store if it was configured, but will not override any other store.
    • Caution: If Bootstrap is run before copying in existing data directories, it will default to PlainFileStore. Then when existing webs with RCS style history or copied in, the wrong store will be active. The PlainFileStore will refuse to save any topic if it detects existing RCS style history. But new topics will be created with incompatible history.
  • The store bootstrap checks if grep is on the path. If available, then it defaults to Forking search for CGI/CLI environments, If it detects Windows, ModPerl or FastCGI, it sets PurePerl for the search.
• Determines the OS and DetailedOS settings.
• Re-reads Foswiki.spec and Config.spec files, applying any other missing defaults.

Bootstrap phase 2

Phase 2 ( bootstrapWebSettings() ) runs only in live web environments. If it detects the CLI engine, it returns without setting any defaults. It establishes defaults for {DefaultUrlHost}, {ScriptUrlPath}, {ScriptUrlPaths}{view} and {PubUrlPath}. Foswiki.pm calls it, passing it the "Action" detected by the Request parsing. (view. jsonrpc. etc.)

key	Setting
protocol	http: or https: set by examining %ENV{HTTPS}
{DefaultUrlHost}	Set from protocol, and hostname extracted from the following. Tried in order: %ENV{HTTP_HOST} %ENV{SERVER_NAME} %ENV{SCRIPT_URI} hardcoded to localhost
{ScriptUrlPath} {ScriptUrlPaths}{view} and {PubUrlPath}	%ENV{PATH_INFO}, %ENV{SCRIPT_URL}, %ENV{SCRIPT_URI}, and %ENV{REQUEST_URI} are examined to figure out if short URLs are in use. {PubUrlPath} is set relative to the bin directory ( bin/../pub/ ) when short URLs are not in use.

The return from Phase 2 is a banner message that includes a link to the configure script. This includes a URL parameter of VIEWPATH=</path/to/view> if any was needed.   Note that when the =configure script, jsonrpc, or any other Foswiki action is run, bootstrap runs again. It is critical to click through from a "view" URL to the configure script to establish proper configuration of short URLs.

configure script Bootstrap continuation

Bootstrap runs again when the user runs bin/configure. It in turn initializes the ConfigurePlugin. The initPlugin phase of ConfigurePlugin plays a key role in the bootstrap process. Because all interaction with jsonrpc by configure is done using POST, the jsonrpc requests made by configure won't have the VIEWPATH available. ConfigurePlugin does the following:

• If defined, copies the VIEWPATH URL parameter into a Session variable or
• retrieves VIEWPATH from the session variable and sets {ScriptUrlPaths}{view} to the retrieved value.
• Examines VIEWPATH. If it does not contain the string /view, then assumes that short URL's are in use, and that the {PubUrlPath} can be set to {ScriptUrlPaths}{view}/pub

Testing note: Once VIEWPATH has been set into the Session variable, it "sticks" If re-running bootstrap, be sure to delete any cookies to force a new session.

Apache CGI Bootstrap

Phase 1

AUTOCONFIG: Found Bin dir: /var/www/foswiki/distro/core/bin, Script name: view using FindBin
AUTOCONFIG: PubDir = /var/www/foswiki/distro/core/pub 
AUTOCONFIG: LocalesDir = /var/www/foswiki/distro/core/locale 
AUTOCONFIG: WorkingDir = /var/www/foswiki/distro/core/working 
AUTOCONFIG: ToolsDir = /var/www/foswiki/distro/core/tools 
AUTOCONFIG: DataDir = /var/www/foswiki/distro/core/data 
AUTOCONFIG: ScriptDir = /var/www/foswiki/distro/core/bin 
AUTOCONFIG: TemplateDir = /var/www/foswiki/distro/core/templates 
AUTOCONFIG: Unable to use PlainFileStore: ,v files were found in data or pub...
AUTOCONFIG: Store configured for RcsLite
AUTOCONFIG: {Store}{SearchAlgorithm} set to Forking
AUTOCONFIG: Detected OS UNIX:  DetailedOS: linux 

Phase 2 Short URLs http://foswiki.com/

AUTOCONFIG: Bootstrap Phase 2 ENTERED
AUTOCONFIG: Set DefaultUrlHost http://foswiki.com from HTTP_HOST foswiki.com 
AUTOCONFIG: REQUEST_URI is /
AUTOCONFIG: SCRIPT_URI  is http://foswiki.com/ 
AUTOCONFIG: PATH_INFO   is / 
AUTOCONFIG: ENGINE      is Foswiki::Engine::CGI
AUTOCONFIG: Calculated prefix  from SCRIPT_URI and SCRIPT_URL
AUTOCONFIG: Building Short URL paths using prefix  
AUTOCONFIG: Using ScriptUrlPath /bin 
AUTOCONFIG: Using {ScriptUrlPaths}{view} 
AUTOCONFIG: Using PubUrlPath: /pub 

Phase 2 Full URLs http://foswiki.com/bin/viewauth/Sandbox/WebHome

AUTOCONFIG: Bootstrap Phase 2 ENTERED
AUTOCONFIG: Set DefaultUrlHost http://foswiki.com from HTTP_HOST foswiki.com 
AUTOCONFIG: REQUEST_URI is /bin/viewauth/Sandbox/WebHome
AUTOCONFIG: SCRIPT_URI  is http://foswiki.com/bin/viewauth/Sandbox/WebHome 
AUTOCONFIG: PATH_INFO   is /Sandbox/WebHome 
AUTOCONFIG: ENGINE      is Foswiki::Engine::CGI
AUTOCONFIG: Calculated prefix /bin/viewauth from SCRIPT_URI and SCRIPT_URL
AUTOCONFIG: SCRIPT viewauth fully contained in REQUEST_URI /bin/viewauth/Sandbox/WebHome, Not short URLs
AUTOCONFIG: Using ScriptUrlPath /bin 
AUTOCONFIG: Using {ScriptUrlPaths}{view} /bin/view
AUTOCONFIG: Using PubUrlPath: /bin/../pub 

Mod Perl bootstrap

Phase 1

AUTOCONFIG: Found Bin dir: /var/www/foswiki/distro/core/bin, Script name:  using FindBin
AUTOCONFIG: DataDir = /var/www/foswiki/distro/core/data
AUTOCONFIG: WorkingDir = /var/www/foswiki/distro/core/working
AUTOCONFIG: ToolsDir = /var/www/foswiki/distro/core/tools
AUTOCONFIG: LocalesDir = /var/www/foswiki/distro/core/locale
AUTOCONFIG: TemplateDir = /var/www/foswiki/distro/core/templates
AUTOCONFIG: ScriptDir = /var/www/foswiki/distro/core/bin
AUTOCONFIG: PubDir = /var/www/foswiki/distro/core/pub
AUTOCONFIG: Store configured for PlainFile
AUTOCONFIG: Unable to use RCSStore: ,pfv files were found in data or pub, ...
AUTOCONFIG: {Store}{SearchAlgorithm} set to Forking
AUTOCONFIG: Detected OS UNIX:  DetailedOS: linux

Short URLs http://ltrunk.com/

AUTOCONFIG: Bootstrap Phase 2 ENTERED
AUTOCONFIG: Set DefaultUrlHost http://ltrunk.com from HTTP_HOST ltrunk.com
AUTOCONFIG: REQUEST_URI is /
AUTOCONFIG: SCRIPT_URI  is http://ltrunk.com/
AUTOCONFIG: PATH_INFO   is /
AUTOCONFIG: ENGINE      is Foswiki::Engine::Apache2::MP20
AUTOCONFIG: Calculated prefix  from SCRIPT_URI and SCRIPT_URL
AUTOCONFIG: Building Short URL paths using prefix
AUTOCONFIG: Using ScriptUrlPath /bin
AUTOCONFIG: Using {ScriptUrlPaths}{view}
AUTOCONFIG: Using PubUrlPath: /pub
AUTOCONFIG: Applied viewpath  from SESSION
AUTOCONFIG: Adjust PubUrlPath relative to viewpath

Long URLs http://ltrunk.com/bin/viewauth/Sandbox/WebHome/

AUTOCONFIG: Bootstrap Phase 2 ENTERED
AUTOCONFIG: Set DefaultUrlHost http://ltrunk.com from HTTP_HOST ltrunk.com 
AUTOCONFIG: REQUEST_URI is /bin/viewauth/Sandbox/WebHome
AUTOCONFIG: SCRIPT_URI  is http://ltrunk.com/bin/viewauth/Sandbox/WebHome 
AUTOCONFIG: PATH_INFO   is /Sandbox/WebHome 
AUTOCONFIG: ENGINE      is Foswiki::Engine::Apache2::MP20
AUTOCONFIG: Calculated prefix /bin/viewauth from SCRIPT_URI and SCRIPT_URL
AUTOCONFIG: SCRIPT viewauth fully contained in REQUEST_URI /bin/viewauth/Sandbox/WebHome, Not short URLs
AUTOCONFIG: Using ScriptUrlPath /bin 
AUTOCONFIG: Using {ScriptUrlPaths}{view} /bin/view
AUTOCONFIG: Using PubUrlPath: /bin/../pub 
AUTOCONFIG: Applied viewpath  from SESSION
AUTOCONFIG: Adjust PubUrlPath relative to viewpath