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