Chapter 9
Setting up Sites

[p]This chapter describes the server model of Lasso Professional Server including how to create and administer multiple independent sites. [/p]

• Overview provides an overview of the server model in Lasso Professional Server.
• Creating Sites describes how to create new sites including initialization of the new site.
• Setting Up Sites describes how to set site preferences and site selection criteria.
• Site Preferences describes how to modify the preferences for a site including the site administrator username and password and SMTP settings.
• Allowed File Paths describes how to establish what file paths users of a site can access.
• Managing Sites describes how to get information about site processes and troubleshoot problems.

Overview

[p]Lasso Professional Server has a multi-site architecture. One master site (or process) accepts all incoming Web requests and routes them to the appropriate child site. This architecture allows different Web sites (e.g. for different clients or projects) to run in effect within their own copy of Lasso Service. Each site has its own settings, datasources, modules, sessions, and global variables. If one site crashes it can be restarted automatically without affecting any of the other sites. [/p]

• The [def]Master Site[/def] is launched with Lasso Service and is responsible for the server-wide settings for Lasso. The master site routes all incoming Web requests to the appropriate child site. The master site is also responsible for the initialization of Lasso and for hosting [code]ServerAdmin.LassoApp[/code]. The master site will automatically restart any child sites if they crash.
• The [def]Default Site[/def] is created when Lasso is installed. The default site is set to receive all incoming Web requests. Lasso can be run with just the default site and master site without any further configuration. As additional sites are added the default site serves to catch any Web requests that are not served by any other site.
• Additional [def]Sites[/def] (or child sites) can be created in [code]ServerAdmin.LassoApp[/code]. Each site launches an additional Lasso Service process and can be configured completely separately from all other sites. If one child site crashes it can be restarted without affecting any of the other child sites.
• [def]Site Criteria[/def] determines how an incoming Web request will be routed. Site criteria includes which Web host names (or IP addresses) should be routed to the site. Site criteria can also specify specific sub-folders within the Web root which should be routed to the site. Each site can have multiple criteria and criteria can have wildcards. This allows one site in Lasso to serve as the back-end for multiple Web hosts or even for multiple sites to serve as the back-end for different parts of the same Web host.
• Server Administration allows certain [def]Site Preferences[/def] to be modified by the server administrator. These include the site administrator username and password, SMTP settings and more. These preferences can be set when a site is created or can be modified in the Sites > Preferences section.
• The server administrator also controls what [def]Allowed File Paths[/def] a site has access to. The [code][File][/code] tags will only work within the file paths specified in the Sites > File Paths section of Server Administration. The site administrator has full access within the specified file paths and can assign permissions for specific paths to groups created within the site. By default sites have access to the Web server root and the file uploads location.

System Requirements

[p]Each site which is configured within [code]ServerAdmin.LassoApp[/code] requires additional resources. By default Lasso launches the master site and default site. Combined, these two processes have comparable system requirements to earlier versions of Lasso. [/p]

[p]Each additional site should have at least 64 MB of available RAM beyond that required for the basic Lasso installation. [/p]

Site Routing Criteria

[p]The master site determines which child site to route incoming Web requests to using the site routing criteria. An incoming request has the following form: [/p]

[pre]http://www.example.com/folder/file.lasso [/pre]

[p]In this request [code]www.example.com[/code] is the host name (or may sometimes be an IP address), [code]/folder/[/code] is the path, and [code]file.lasso [/code]is the particular file being requested. Lasso looks at the host name and path when determining where to route an incoming request. [/p]

How Lasso routes incoming requests based on site criteria:

1. The incoming host name is checked against each of the site routing criteria. The [code]%[/code] symbol can be used as a wildcard within the criteria in order to match multiple host names. The default site has a host name of simply [code]%[/code] which matches any incoming host name.

• A site which should match for a specific site name might have a criteria of [code]%example.com[/code] in order to match against [code]www.example.com[/code], [code]example.com[/code], [code]mail.example.com[/code], etc. A site can have multiple criteria if it needs to match multiple host names which can’t be defined using a wildcard.

2. The incoming path is matched against the host root in each of the site criteria. The [code]%[/code] symbol can be used as a wildcard within the criteria in order to match multiple paths. The default site has a host path of simply [code]/%[/code] which matches any incoming path. Any sites which should match only against the host name should use the [code]/%[/code] criteria for the host path.

• A site which should match for a specific folder might have a criteria of [code]/folder/%[/code] in order to match against [code]/folder/default.lasso[/code], [code]/folder/subfolder/default.lasso[/code], etc. A site might also have a criteria such as [code]%/mail/%[/code] to match any paths that contain the folder [code]mail[/code]. Or, a criteria of [code]%MyLassoApp.LassoApp[/code] to serve a specific LassoApp from the site.

3. If multiple site criteria match an incoming request then the criteria with the longest host name and host path will be used. This means that the request will be routed to the site with most specific host name or host path criteria.

[note][b]Note: [/b]The master site has built-in routing criteria. The Lasso initialization screen and [code]ServerAdmin.LassoApp[/code] are automatically served from the master site. [/note]

Site Modules and Folders

[p]The Lasso Professional Server application folder is divided into two levels. The master level includes all of the folders within the Lasso Professional Server application folder itself. The site level includes equivalent site-specific folders within the [code]LassoSites[/code] folder. [/p]

[p]The master level includes the following folders: [/p]

[pre]JavaLibraries LassoModules
JDBCDrivers LassoSites
LassoAdmin LassoStartup
LassoApps SQLIteDBs
LassoLibraries [/pre]

[p]The [code]LassoSites[/code] folder includes a subfolder for each site. By default there is one subfolder named [code]default-1[/code] which corresponds to the default site. With the exception of the [code]LassoSites[/code] folder, each site specific folder contains the same folders as the master level: [/p]

[pre]JavaLibraries LassoLibraries
JDBCDrivers LassoModules
LassoAdmin LassoStartup
LassoApps SQLIteDB [/pre]

[p]By default, all of the site level folders except [code]SQLiteDBs[/code] are empty. [code]SQLiteDBs[/code] contains the [code]lasso_admin[/code], [code]lasso_internal[/code], and [code]lasso_site_#[/code] databases that hold the settings and preferences for the site. [/p]

[p]Each site level folder contains a [code]LassoErrors.txt[/code] file that records errors for the particular site based on the error routing preferences. The [code]LassoErrors.txt[/code] file in the master level only records errors for the master site. [/p]

[p]When Lasso requires a resource it looks in both the site level and the master level, but the order depends on the particular resource: [/p]

• [def]JavaLibraries[/def] – All libraries which are included in the master and site levels are loaded when Java is started for each site. There should be no duplicate libraries between the site and master levels.
• [def]JDBCDrivers[/def] – All drivers which are included in the master and site levels are loaded when Java is started for each site. There should be no duplicate drivers between the site and master levels.

1. [note][b]Note: [/b]The master site does not load Java so no JavaLibraries or JDBCDrivers are loaded in the master site. [/note]

• [def]LassoAdmin[/def] – The site level master admin is used for storage of backups, imports, exports, and created LassoApps. If a custom [code]error.lasso[/code] page is located at the site level then it is used to format error messages, otherwise the default [code]error.lasso[/code] file from the server level is used.
• [def]LassoApps[/def] – This folder contains LassoApps that will be served on-demand. When a LassoApp is requested the site level is checked first. If the LassoApp is not found then the server level is checked.
• [def]LassoLibraries[/def] – This folder contains on-demand tag libraries. When an unknown tag is called the site level folder is searched first for a file corresponding to the namespace of the unknown tag. If no tag library is found then the server level is checked.
• [def]LassoModules[/def] – All modules in both the server level and site level folders are loaded when each site starts up. Modules in the server level folder are available to every site while modules in the site level folder are available only to one specific site.

1. [note][b]Note: [/b]The master site does not load any modules. [/note]

• [def]LassoStartup[/def] – All items in both the server level and site level folders are loaded when each sites starts up. The items in the server level folder are loaded first, followed by the items in the site level folder.
• [code]Startup.LassoApp[/code] is a special case. [code]Startup.LassoApp[/code] is always loaded before the other startup items. By default there is one [code]Startup.LassoApp[/code] in the master level folder. If [code]Startup.LassoApp[/code] is located in the site level folder then it is loaded prior to loading any items in either the master or site level folders and the master level [code]Startup.LassoApp[/code] is not loaded. This allows a site-specific [code]Startup.LassoApp[/code] to override the default [code]Startup.LassoApp[/code].

1. [note][b]Note: [/b]The master site only loads [code]Startup.LassoApp[/code] from the master level and no other startup items. [/note]

• [def]SQLiteDBs[/def] – Each site only has access to its own site level SQLite databases. The master site has access to the master level SQLite databases and also to all of the site level databases through special aliases. See the Site Databases section in Managing Sites for more details.

Site Independence

[p]Each site within Lasso is completely independent from the other sites: [/p]

• [def]Settings[/def] – Each site has its own preferences and settings which are established within [code]SiteAdmin.LassoApp[/code]. The site administration can be accessed by either the site administrator or the server administrator. The server administrator can reset each site administrator’s password.
• [def]Crashes[/def] – If one site crashes, no other sites are affected. The master site will restart the site for the next incoming Web request that routes to the site.
• [def]Errors[/def] – Each site maintains its own [code]errors[/code] database in [code]lasso_internal[/code] and its own [code]LassoErrors.txt[/code] file within the site level folder.
• [def]Data Sources[/def] – All data source hosts are set up for each site independently. This allows different sites to access completely different data sources or use different authentication information. The data sources which are available to the site include all modules and JDBC drivers within the site level and the master level folders.
• [def]Tags[/def] – Each site has its own collection of tags. The available tags depend on what startup items and modules are loaded by the site. In addition, the server administrator can deactivate specific tags for every site on the server.
• [def]Groups and Users[/def] – Each site has its own set of groups and users. All security settings for a group apply only within the site. Usernames only exist with the site and there is no automatic way to synch them between multiple sites.
• [def]Sessions[/def] – Sessions can only be reloaded from within the same site they were stored. There is no way to access one site’s sessions from another site.
• [def]Email Queue[/def] – Each site is responsible for managing its own email queue. Pending messages can be seen from within [code]SiteAdmin.LassoApp[/code].
• [def]Scheduled Tasks[/def] – Each site has its own scheduled events queue. However, since scheduled events are simply URLs it is possible for one site to call another (or a completely different Web site).
• [def]Global Variables[/def] – Each site has its own set of global variables. There is no way to share global variables between site and it is impossible for users of one site to get access to global variables on another site.
• [def]Tag Libraries[/def] – Each site can have its own collection of tag libraries which are loaded on-demand. Or, tag libraries which aren’t found at the site level can be loaded from the master level.
• [def]LassoApps[/def] – Each site has its own collection of loaded LassoApps. A LassoApp which is loaded on one site will not be available to any other sites. On-demand LassoApps can be loaded from the site level or from the master level.

Setting Up Sites

[p]Sites are created in the Sites > Sites section of [code]ServerAdmin.LassoApp[/code]. The default site is initially configured to catch all incoming Web requests. Many Lasso installations will only need to use this default site. Additional sites can be created for any of the following reasons: [/p]

• A Web hosting provider can create one site for each client on a server. This allows each client to use their own custom modules, startup items, data sources, security settings, global variables, etc. And prevents coding problems by one client to affect another client.
• A developer who hosts multiple sites may want to create one host for each site. This allows sessions and other settings to be applied to each site specifically.
• A site can be created for development purposes. This allows code which is being debugged to be tested separately from the deployment site. Once code is debugged and stable it can be moved over to the deployment site.

Figure 1: Sites List Page

[p]The [code]Site Listing[/code] panel shows a list of all the sites that are defined in Lasso. Each site includes its ID, name, enabled status, running status, and a link to the [code]SiteAdmin.LassoApp[/code] for the site. [/p]

[p]Selecting an individual site will show its settings in the right panel. [code]Enable All[/code] will enable all defined sites. [code]Disable All[/code] will disable all defined sites except for the default site. When a site is disabled it is also stopped. [/p]

Creating a Site

[p]Selecting the [code]Create…[/code]button will show the [code]Add Site[/code] panel to the right. [/p]

Figure 2: Add Site Panel

To add a new site:

1. Enter a name of the site. Site names should consist of only alphanumeric characters and the underscore. The site level folders will be stored in a folder with the entered name, a dash, and the site ID. For example, [code]New_Site_6[/code].

2. Enter the site criteria. The host path matches against the host name or IP address of incoming Web requests. The [code]%[/code] symbol can be used as a wildcard to match multiple host names. Host names are usually entered as [code]%example[/code].com to match [code]www.example.com[/code] or [code]example.com[/code].

• The host path should be [code]/%[/code] to match any paths on the desired host. If the site should match only a specific subfolder of the desired host then the path can be entered as [code]/folder/%[/code].

3. The [code]Description[/code] field can be used to store notes about the site.

4. The [code]Duplicate Site[/code] popup can be used to optionally copy all of the site level folders from an existing site to serve as the basis of the new site. Otherwise, default settings will be used for the new site.

5. If [code]Install Lasso Reference[/code] option is set to [code]Yes[/code] then the [code]LassoScript8_Reference[/code] will be copied into the site. This database is required in order to use the local copy of the Lasso Reference.

6. The [code]Administrator Username[/code] and [code]Password[/code] can be established for the new site. The site administrator will need this username and password to access the site’s settings through [code]SiteAdmin.LassoApp[/code]. The username cannot match that selected for the server administrator.
7. [note][b]Note: [/b]The server administrator can also access each site’s settings using [code]SiteAdmin.LassoApp[/code] with the server administrator username and password. [/note]

7. The [code]Prompt for Initialization[/code] option will prompt the site administrator to change their username and password and establish some other settings the first time they access [code]SiteAdmin.LassoApp[/code].

8. The SMTP settings allow the host, port, and SMTP AUTH username and password for the site to be established. By default, these settings match those which were set when Lasso was initialized.
9. [note][b]Note: [/b]The site administrator username and password and site preferences can be modified on the Sites > Preferences section once the site is created. [/note]

[p]After selecting the [code]Add Site…[/code] button the newly added site is selected for additional modifications. If the site is enabled it will be started automatically. If the site is disabled it will not be started. [/p]

[p]The following section describes the actions that Lasso takes when it creates a new site. [/p]

How Lasso creates a new site:

1. The site name and criteria are validated. A folder named with the site name and ID is created in [code]LassoSites[/code].

2. If a site has been selected for duplication then all of the site level folders for that site are copied to the new folder.

3. The Lasso Reference database is copied if required.

4. The site is started. Any additional required site level folders are created automatically. If the site level databases have not been duplicated then they are created automatically.

5. The site level [code]lasso_internal[/code] database is accessed so the site administrator username and password and SMTP settings can be stored.

6. The default allowed file paths of the Web server root and file upload path are added to the site.

Updating Site Properties

[p]Selecting a site name in the [code]Sites Listing[/code] panel will shows its details in the [code]Site Detail[/code] panel which appears to the right. Here, the server administrator can update the sites properties and site criteria. Site preferences can be modified in the Sites > Preferences section and allows file paths can be modified in in the Sites > File Paths section. [/p]

To update details for a specific site:

1. The name and ID of the site are fixed after it is created. They cannot be modified.

2. A site can be enabled or disabled. If a site is disabled it will be stopped and will not be automatically started the next time Lasso is launched. Enabled sites are automatically started each time Lasso is launched.

3. The [code]Description[/code] field can be used to store notes about the site.

4. The [code]Site Admin URL[/code] is generated automatically based on the site criteria and is used for the [code]Admin[/code] link in the site listing. The URL can be modified if required so it properly loads [code]SiteAdmin.LassoApp[/code] for the site.

5. The [code]Site Criteria[/code] are established in a listing each with a [code]Host Name[/code] and [code]Host Path[/code]. The [code]%[/code] symbol can be used as a wildcard in either field. New site criteria can be added by inserting values into the [code]New[/code] line then selecting [code]Update[/code]. Site criteria can be deleted using the minus button next to each line.

[p]All of the specified changes are made when the [code]Update[/code] button is selected. [/p]

Stopping or Starting a Site

[p]Selecting a site name in the [code]Sites Listing[/code] panel will shows its details in the [code]Site Detail[/code] panel which appears to the right. Here, the server administrator can start or stop the specified site. [/p]

To start a site:

[p]Select the [code]Start[/code] button at the bottom of the [code]Site Detail[/code] panel. The [code]Start[/code] button will only be visible if the site is currently stopped. [/p]

[note][b]Note: [/b]Disabled sites can be started, but will not be automatically restarted if they crash. Disabled sites are not started automatically when Lasso is launched. [/note]

To stop a site:

[p]Select the [code]Stop[/code] button at the bottom of the [code]Site Detail[/code] panel. The [code]Stop[/code] button will only be visible if the site is currently running. [/p]

[note][b]Note: [/b]Enabled sites can be stopped, but will automatically restart if an incoming Web request is routed to the site. Enabled sites will be started automatically when Lasso is launched. [/note]

To restart a site:

[p]A site can be restarted by first stopping the site, then starting it again. An enabled site which is stopped will also automatically restart when an incoming Web request is routed to the site or if Lasso is relaunched. [/p]

Deleting a Site

[p]Selecting a site name in the [code]Sites Listing[/code] panel will shows its details in the [code]Site Detail[/code] panel which appears to the right. Here, the server administrator can delete the specified site. [/p]

To delete a site:

[p]Select the [code]Delete…[/code] button within the [code]Site Detail[/code] panel and confirm the dialog that appears. The site is stopped and deleted from within Lasso’s settings. [/p]

[p]The site level folders for the site are moved to a [code]LassoSitesDeleted[/code] folder. To completely delete a site the corresponding site level folder must also be deleted from the [code]LassoSitesDeleted[/code] folder. [/p]

Site Preferences

[p]The Sites > Preferences section allows the site preferences to be modified. These include the site administrator username and password and the default SMTP settings for sending mail. [/p]

Figure 3: Site Preferences

[p]The control at the top of the section allows the current site to be selected. Details of the current site are also provided in the left panel. Sites cannot be started and stopped through this interface. The Sites > Sites section should be used instead. [/p]

[p]The Prompt for Initialization option controls whether the site administrator will be prompted for a new username and password the next time they log in to Site Administration. This allows the site administrator username and password to be set to a temporary value and then reset by the actual administrator to a value they choose. [/p]

Allowed Files Paths

[p]Lasso has built-in file security for site users and site administrators. A site can only access the allowed file paths that are established in the Sites > File Paths section of Server Administration. [/p]

Figure 4: Allowed File Paths

[p]The control at the top of the section allows the current site to be selected. Details of the current site are also provided in the left panel. Sites cannot be started and stopped through this interface. The Sites > Sites section should be used instead. [/p]

[p]The left panel shows the file paths that are currently allowed for the site. The [code][File][/code] tags will only work within a path that is defined in this panel for either the users or the site administrator of the current site. Paths can be deleted by selecting the minus symbol next to a path. Paths can be added by typing the name of the path in the text input and then selecting Add Path. [/p]

[note][b]Important: [/b]The site administrator controls what permissions are assigned to a path. If a path is deleted and recreated within this interface then those permissions will be lost. [/note]

[p]Several special purpose paths can be added automatically using the buttons at the bottom of the panel if they are not already included in the list of allowed paths. These include the Web server root path [code]/[/code] and the file uploads path (established in the right panel). [/p]

File Uploads Path

[p]The right panel allows the file uploads path to be established. This path can vary depending on platform, operating system version, local volume names, and Web server. The most foolproof way to determine the file uploads path is to try a file upload and then store the location of the uploaded temporary file. [/p]

[p]The current file uploads path is displayed at the top of the panel. As long as this value is not [code]Undefined[/code] it should not need to be redefined unless Lasso has been moved to a different machine. A new file uploads path can be determined by selecting a small (32k or less) file with the [code]Choose File[/code] control and then selecting the [code]Test[/code] button. The uploaded file will be deleted immediately after its location has been determined. [/p]

[p]The path which is determined with this procedure can then be added to the list of allowed paths using the [code]Allow File Upload Path[/code] button at the bottom of the left panel (if the path is not already in the list of allowed paths). Newly created sites will have this path allowed by default. [/p]

Managing Sites

[p]This section includes technical details about sites in Lasso including how they are represented within system administration tools on each platform, what error messages they report, and how to troubleshoot problems. [/p]

Site Processes

[p]Each individual site which is running in Lasso is seen as a separate process by the operating system. [/p]

• [def]Mac OS X[/def] – Within the Activity Monitor or top or [code]ps[/code] within the Terminal, each site will appear as a separate instance of Lasso Service. A default installation will consist of two instances of Lasso Service, one for the master site and one for the default site.
• The following command can be used to list all of the site processes that are currently running. The command line arguments listed with each process help to identify which site each process corresponds to.

[pre]ps -U lasso [/pre]

[pre]➜ 11689 p1 S+ 0:03.50 ./Lasso8Service
11690 p1 S+ 0:27.56 ./Lasso8Service--nolisten --ischild --siteid=1
--sitename=default --pipename=lassosite_1 --workingdir=LassoSites/default-1 [/pre]

• [def]Windows[/def] – Within the Services control panel only the master Lasso Service will be listed. The other site processes can be viewed by accessing the Windows Task Manager ([code]Ctrl-Alt-Delete[/code]) and selecting the [code]Processes[/code] tab. Each Lasso Service process will appear with image name [code]LassoService.exe[/code].

Error Messages

[p]Lasso logs error messages related to site operations within the [code]errors[/code] database and [code]LassoErrors.txt[/code] file for the master site. Informative messages about the normal operation of sites are logged at the [code]Warning[/code] level. Serious problems are logged at the [code]Critical[/code] level. [/p]

• When the master site has to restart a site process the following message is logged as a [code]Warning[/code]. This could indicate that the site process crashed or was restarted by an administrator.

[pre]Restarted site process <id> <name>. [/pre]

• The rest of these errors are reported at the [code]Critical[/code] level and only appear if a serious problem starting, connecting to, or restarting a site has been encountered. If one of these errors occurs the entire Lasso Service process should be stopped and then restarted.

[pre]Unable to hand request to site process even after restarting it <id> <name>.
Unable to restart site process <id> <name>.
Unable to get PID from child process for site <id> <name>.
Unable to create child process for site <id> <name>.
Child process failed to create named pipe for site <id> <name>. [/pre]