The same installation can be used to both develop and deploy an OpenLaszlo application. Alternatively, you may use a separate installation to deploy your OpenLaszlo applications.

Conventions used in the remainder of this document:

Once you have chosen and installed a servlet container, you may need to adjust some of its default configuration settings. In particular, you may need to configure the default TCP/IP port and secure (SSL/https) TCP/IP port. You may also need to configure the container's JVM settings like the initial and maximum heap sizes (see below) and the default and maximum number of threads.

Some servlet containers may also be configured with web servers like the Apache HTTPD web server sitting in front of them. The precise details for how to set up configurations like this, as well as the how to adjust the settings mentioned above are beyond the scope of this document; see your servlet container documentation for details. However, see below for more details on which parameters you may need to set.

4.1.1. Setting compression

For best results, you may need to change your servelet container's compression settings, especially for DHTML applications. You can use an internet search engine using a phrase gzip followed by your server, e.g. 'gzip tomcat'. For example, here's a typical tomcat/conf/server.xml

   <Connector acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true" port="8080" redirectPort="8443"
               compression="on"
               compressionMinSize="2048"
               noCompressionUserAgents="gozilla, traviata"
               compressableMimeType="text/html,text/xml,text/javascript,application/x-javascript,application/javascript">
    </Connector>
    <Connector acceptCount="100" disableUploadTimeout="true" port="8443" scheme="https" secure="true" sslProtocol="TLS" keystoreFile="conf/lzkeystore" keystorePass="changeit"
               compression="on"
               compressionMinSize="2048"
               noCompressionUserAgents="gozilla, traviata"
               compressableMimeType="text/html,text/xml,text/javascript,application/x-javascript,application/javascript">
    </Connector>

You can set the heap sizes via the -Xmx and -Xms command line options such

JAVA_OPTS='-Xmx512 -Xms256m'

which will set both the initial heap size to 256 MBytes and maximum heap sizes to 512 MBytes. See your servlet container documentation, in particular, for where to place this setting.

Note that the DNS hostname of the computer running the servlet container as well as the TCP/IP port(s) on which it listens will surface as part of the URL that will be used to access your OpenLaszlo application when it is deployed. In the remainder of this document, we will use the hostname host and port number $port to indicate the values of these settings.

To run the OpenLaszlo Server you must have the Java SDK (sometimes called the JDK, J2SDK, or J2SE SDK), not just the JRE, version 1.4 or greater. It's available at http://java.sun.com/j2se/1.4.2/download.html (click the Download J2SE SDK link).

	Note
	Mac OSX users do not have to install the SDK, as it is installed with OSX by default.

To create an empty OpenLaszlo-enabled webapp, you simply create a new directory and copy in the WEB-INF directory from the lps-5.0.x webapp. On a UNIX system, do

mkdir myappcp -r $LPS-WEBAPPDIR/WEB-INF myappcp -r $LPS-WEBAPPDIR/lps myapp

where $LPS-WEBAPPDIR is the path to a copy of the lps-5.0.x web application. For LPS (standard) distribution, $LPS-WEBAPPDIR is $INSTALLDIR/Server/lps-5.0.x.

To place your Laszlo applications inside myapp, copy the LZX (.lzx extension) files and art assets for your Laszlo application(s) inside the myapp directory.

To deploy the webapp, follow your servlet container's instructions.

	Note
	Note that the lps-5.0.x webapp that is packaged with LPS comes pre-configured for development, not deployment. Before deploying your applications you will need to reconfigure the OpenLaszlo Server for deployment, as explained in the next section.

The OpenLaszlo Server comes with several assets, such as documentation and examples, that you may not need or want to deploy with your OpenLaszlo application. To create a minimal deployment configuration: (For LPS 2.2 and later).

Now you can safely remove everything under the webapp except the WEB-INF directory and the lps directory. keeping only:

You should also remove

lps-3.1/lps/utils

as it includes the source code viewer jsp and other unneeded utilities.

By default, the OpenLaszlo proxy server ships "wide open". See the discussion of security, below. See also the section on white listing and black listing for instructions on how to change this default behavior.

The files that are used to configure the OpenLaszlo Server are:

Changing settings in any of these files will require that the OpenLaszlo-enabled web application be restarted. See your servlet container documentation for instructions on how to restart. For the OpenLaszlo (standard) distribution, you can simply stop and re-start Tomcat.

This file is used to configure the webapp that houses OpenLaszlo applications as well as the main OpenLaszlo servlet.

The web.xml must contain a servlet declaration that uses the org.openlaszlo.servlets.LZServlet class like:

<servlet>
  <servlet-name>LPS</servlet-name>
  <servlet-class>org.openlaszlo.servlets.LZServlet</servlet-class>
</servlet>

There should be a servlet mapping that maps all .lzx files to this servlet like:

<servlet-mapping>
  <servlet-name>LPS</servlet-name>
  <url-pattern>*.lzx</url-pattern>
</servlet-mapping>

There are also other settings you can make here that affect the authentication scheme used by the OpenLaszlo Server to authenticate use of the OpenLaszlo Server's persistent connection feature. See ??? for more details.

This file contains numerous settings that affect LPS operation. Below is the lps.properties file that ships with LPS.

#===============================================================================
# LPS properties file for development
#===============================================================================
# * P_LZ_COPYRIGHT_BEGIN ******************************************************
# * Copyright 2001-2008 Laszlo Systems, Inc.  All Rights Reserved.            *
# * Use is subject to license terms.                                          *
# * P_LZ_COPYRIGHT_END ********************************************************

#===============================================================================
# Default request type for naked .lzx requests (requests with no (or unknown) lzt 
# query string).  For development, you want 'app_console'.  For deployment, you
# want 'html'.
#defaultRequestType=html
defaultRequestType=app_console

#===============================================================================
# Request toggles - many of these should be set to false 
# for deployment.
allowRequestXML=true
allowRequestINFO=true
allowRequestSOURCE=true
allowRequestFILTER=true


# The following requests will require the admin. password if set below
allowRequestCLEARCACHE=true
allowRequestCLEARLOG=true
allowRequestLOG=true
allowRequestLOGCONFIG=true
allowRequestGC=true
allowRequestCACHEINFO=true
allowRequestSETCACHESIZE=true
allowRequestSERVERINFO=true
allowRequestERRORCOUNT=true
allowRequestSTAT=true
allowRequestCONNECTIONINFO=true
allowRequestJAVARPCINFO=true
allowRequestSOAPINFO=true
allowRequestXMLRPCINFO=true

#===============================================================================
# Allow forced recompile (will require admin password if reset)
allowRecompile=true

#===============================================================================
# Uncomment for stat (default is true) and url collection (default is false)
#collectStat=true
#dataRequest.collectURL=true
#mediaRequest.collectURL=true

#===============================================================================
# Password to check for administrative requests.
# Uncomment and admin requests will require this passwd in the query
# string as ?pwd=your_passwd_here
#adminPassword=SET_ME_PLEASE

#===============================================================================
## Backend http properties
#
#http.maxConns=1000
#http.maxConnsPerHost=1000
# The number of redirects to try (security issue; default is 0)
http.followRedirects=3
# Timeout for back-end http requests
#http.backendTimeout=30000
#http.backendConnectionTimeout=30000

#===============================================================================
# Compilation manager dependency options: 
#
# never - compile once
# check  - check all includes
# always - compile for each access
#
# 'never' results in highest performance, requires an ?lzrecompile=true request
# to recompile the application.
compMgrDependencyOption=check

#===============================================================================
# Cache settings
#
# Locations of cache directories
# The default location is inside the WEB-INF/lps/work directory
# of your web application.  

# Compilation cache
#cache.directory=WEB-INF/lps/work/cache
# Compilation media cache
#cmcache.directory=WEB-INF/lps/work/cache/cmcache
# Script compiler cache
#scache.directory=WEB-INF/lps/work/scache

# Runtime Media cache
#mcache.directory=WEB-INF/lps/work/mcache
# Runtime Data cache
#dcache.directory=WEB-INF/lps/work/dcache

# Cache sizes (0 = disabled (or allow 1 item for disk caches), -1 means infinite)
# Defaults are 500000000 for disk and 1000000 for mem
#mcache.disk.size=500000000
#mcache.mem.size=1000000

# Max size allowable for an item to be cached in memory
# in the media cache (some media files are big and we
# need to keep them on disk only).
mcache.mem.item.max=1000000

# Cache sizes (0 = disabled (or allow 1 item for disk caches), -1 means infinite)
# Defaults are 500000000 for disk and 1000000 for mem
#dcache.disk.size=500000000
#dcache.mem.size=1000000

# Compiler Media Cache
# there is no need to keep any of these files in memory
cmcache.mem.size=0

# Keeps script cache small
scache.disk.size=10000000
scache.mem.size=1000000

#===============================================================================
# Apache AXIS settings

# Defaults to WEB-INF/lps/config/client-config.wsdd
# axis.clientConfigFile=client-config.wsdd

#===============================================================================
# WSDL load options: 
#
# never - loads once
# always - loads for each access
#
# 'never' results in highest performance
rpc.soap.wsdlLoadOption=always

#===============================================================================
# Persistent connection properties
maxMessageLen=2000
connectionLength=65536

#===============================================================================

#===============================================================================
# Compiler parameters
compiler.runtime.default=swf8

In general, when you go to deploy an OpenLaszlo application, you may wish to disable certain request types. The OpenLaszlo Server supports numerous request types that are indicated via the ?lzt query string variable in an URL. You can specify the default request type for URLs that don't specify ?lzt via the defaultRequestType property.

There are three values for this property:

In general, deployments where the LZX source files and assets are fixed should use never. For deployments where LZX source and/or art assets may change, you should use check. If you choose never and need to update the application, you may provide the lzrecompile=true query string at the end of a request for the application. You may also need to provide the administrator password for this to take affect.

The server uses several caches that are maintained via a standard LRU (least recently used) algorithm. Each caches can be configured independently and each one can be set to use disk only or memory (backed by disk) plus additional disk space. The caches (and their names) are:

In general, it helps to know the expected number and size of the items being cached to optimally tune some of these numbers. Here's the list:

name is one of cache, dcache, mcache, cmcache.

Note that the amount of disk space a cache will use is actually name.disk.size + name.mem.size. Also note that the cache will does not keep track of the amount of disk space used for meta data. For smaller items, the meta data can be significant.

Each cache has two properties that affect its performance: initial capacity (mapsize) and load factor (load). The capacity is the number of buckets in a hash table, and the initial capacity is simply the capacity at the time the hash table is created. The load factor is a measure of how full the hash table is allowed to get before its capacity is automatically increased. When the number of entries in the hash table exceeds the product of the load factor and the current capacity, the capacity is roughly doubled by calling the rehash() method.

As a general rule, the default load factor (.75) offers a good tradeoff between time and space costs. Higher values decrease the space overhead but increase the lookup cost (reflected in most of the operations of the HashMap class, including get() and put()). The expected number of entries in the map and its load factor should be taken into account when setting its initial capacity, so as to minimize the number of rehash() operations. If the initial capacity is greater than the maximum number of entries divided by the load factor, no rehash() operations will ever occur.

The lps.xml file contains configuration options for

Here is an example on what this file can look like:

<lps-configuration>

    <!-- Default options -->
    <option name="content-encoding-user-agent" >
        <deny>
            <!-- Deny Netscape 4.7* -->
            <pattern>Mozilla/4\.7[0-9]* .*</pattern>
        </deny>
    </option>

    <option name="connection-user-agent" >
        <deny>
            <!-- Deny Safari -->
            <pattern>Safari</pattern>
        </deny>
    </option>

    <application path="/examples/dataimage.lzx" >
        <option name="proxy-security-urls">
            <allow>
                <pattern>http://.*\.images\.com/.*</pattern>
                <pattern>http://.*\.adobe\.com/.*</pattern>
            </allow>
        </option> 
    </application>

    <application path="/examples/data.lzx" >
        <option name="proxy-security-urls" >
            <deny>
                <pattern>http://.*\.foobar\.net/.*</pattern>
            </deny>
        </option> 
    </application>

    <!-- Deny requests under /secret in the foobar.com domain -->
    <!-- for LZX files that begin with /data.                 -->
    <application pattern="/data.*\.lzx" >
        <option name="proxy-security-urls" >
            <deny>
                <pattern>http://*\.foobar\.net/.*</pattern>
            </deny>
        </option> 
    </application>

</lps-configuration>

The root element of lps.xml is <lps-configuration> and only two valid tags exist:

Any <option> tag defined under <lps-configuration> is considered a global default. This default option may be overridden by using the <application> tag.

The <option> tag has one attribute called name that takes one of the following values:

    <option name="content-encoding-user-agent" >
        <deny>
            <pattern>Mozilla/4\.7[0-9]* .*</pattern>
        </deny>
    </option>

    <option name="proxy-security-urls" >
        <allow>
            <pattern>http://.*\.laszlosystems\.com/.*</pattern>
            <pattern>http://.*\.foobar\.com/.*</pattern>
        </allow>
    </option>

    <application path="/examples/dataimage.lzx">
        <option name="proxy-security-urls">
            <allow>
                <pattern>http://.*\.images\.com/.*</pattern>
                <pattern>http://.*\.adobe\.com/.*</pattern>
            </allow>
        </option> 
    </application>

    <application pattern="/examples/data.*\.lzx" >
        <option name="proxy-security-urls">
            <deny>
                <pattern>http://.*\.foobar\.com/.*</pattern>
            </deny>
        </option> 
    </application>

The OpenLaszlo Server provides a highly configurable and efficient logging mechanism that you can use to debug and monitor server activities.

The server uses the well-known Log4j package for logging details about its operation. You can configure LPS logging by modifying elements of the log4j:configuration tag in the lps.xml configuration file. The default location for the detailed log file is inside the web application's WEB-INF directory at $webapp/WEB-INF/lps/work/logs/lps.log.

You can change the location of this file using a "File" parameter in the lps appender. For example,

<appender name="lps" class="org.apache.log4j.RollingFileAppender">
  <param name="File" value="lps.log"/>
    <!-- other settings here -->
</appender>

will leave the log in the default location inside the web applications's WEB-INF directory. You can also modify the amount of logging done by changing the priority of your logger from info to debug. For more details on this file see the online manual There's also the detailed doc about the pattern layout for controlling the format of each log statement. The default settings will keep 5 backup log files each with a maximum size of 10 MBytes. You can change them by using the MaxBackupIndex param and MaxFileSize param in the lps appender. For example, the following will keep 20 backup log files with a maximum size of 5 MBytes.

<appender name="lps" class="org.apache.log4j.RollingFileAppender">
  <param name="MaxBackupIndex" value="20"/>
  <param name="MaxFileSize" value="5MB"/>
  <!-- other settings here -->
</appender>

Your servlet container will likely maintain logs of its own. See your servlet container documentation of the location and configuration of these logs.

The default configuration that ships with the OpenLaszlo Server also includes a logger named, org.openlaszlo.exceptions. The server will log unexpected exceptions to this logger. During development this logger should be left as WARN or ERROR level, but most deployments will prefer to comment it out, unless they are troubleshooting.

    lzt=logconfig&xml=%3Clog4j:configuration%3E...%3C/log4j:configuration%3E

    lzt=logconfig&xml=...&save=1

This file contains the set of users recognized by the default security servlet (used by the default OpenLaszlo Server authenticator interface). The authenticator is used by to authenticate users who attempt to connect to the ther sever via the Persistent Connection Manager.

In parallel with the config directory in WEB-INF/lps there is a directory named config-deploy which contains a sample OpenLaszlo configuration for deployment purposes. To use this directory, simply delete, move, or rename the config directory out of the way and copy, rename the config-deploy one to config. You should definitely review the configuration and modify it to suit your needs. Of course you will have to (re)start your OpenLaszlo Server.

As noted above, by default the OpenLaszlo Server is set up as an open proxy. As with any servlet (or CGI), the OpenLaszlo Server is a program that responds to web queries. When connected to the big, bad, internet, it is possible that an unexpected or malformed query can exercise an unexpected code path that could lead to failure of the servlet or to the servlet's being exploited to take control of the server on which it is hosted. Therefore the OpenLaszlo Server should not be deployed as an open server without careful consideration of these issues. If you are using Tomcat as your servlet container, we recommend the security chapter of the O'Reilly Tomcat book which discusses how to secure a Tomcat server. If you are using another servlet container, you should consult that provider's documentation on how to best secure your system.

In addition, you can use OpenLaszlo'swhite-listing and black-listing capabilities to limit access.

The OpenLaszlo Server and OpenLaszlo applications inherit the security of the container in/from which they are deployed. If you would like to serve OpenLaszlo applications over secure HTTPS transport, you will need to enable this feature in your servlet container.

With few exceptions, OpenLaszlo applications work identically when served over HTTPS. The two exceptions are:

OpenLaszlo applications served over standard (insecure) HTTP transport can make secure runtime HTTPS requests. These requests are transported securely from the client to the OpenLaszlo Server. (They are also transported securely from any back-end to the server itself).

SWF only: The features described in this section only work in applications compiled to SWF. They do not work in applications compiled to other runtimes.

OpenLaszlo applications served over (insecure) HTTP that run in the Macromedia Flash 7 player may require additional server configuration to access runtime data and media over secure HTTPS. According to Macromedia documentation, you will need to provide a cross-domain policy file that explicitly allows such access to your remote data. OpenLaszlo provides a sample (and lenient) cross-domain policy file ($WEBAPP/WEB-INF/lps/config/crossdomain.xml) that, when copied to the root directory of the front-most server that serves the OpenLaszlo application, will enable HTTPS access from applications that are loaded over (insecure) HTTP from any server. If you need to support HTTPS access from HTTP-loaded apps, you should read this example file and follow the instructions inside it before copying. See the Macromedia article on security in Flash 7 for details on the format and interpretation of the cross-domain policy file.

If you are running the OpenLaszlo Server inside a servlet container and the servlet container is directly accessible, then the file crossdomain.xml should be placed in container's ROOT web application. See your servlet container's documentation for locating this directory. If you are fronting your container with another server such as Apache, this file needs to be placed in that server's root directory. For example, with Apache, this would be Apache's DocumentRoot directory (or the root of Apache's virtual host directory for the host that's serving the application).

The configuration of your servlet container (or front-side server) can also affect the security of the LPS. To prevent certain denial-of-service (DOS) attacks, you may want to configure the max size of an HTTP request body, the maximum size of an HTTP request header, the maximum number of HTTP headers in a request, and the maximum size of the initial request line (url and query string).

The OpenLaszlo Source Viewer, which ships with the OpenLaszlo Server, allows anyone with internet access to read any XML files, including sources to any .lzx program, in your LPS directory by using a query such as, for example, http://127.0.0.1:8080/lps/lps/utils/viewer/viewer.jsp?file=/examples/tag-definition.lzx.

To prevent this, remove or rename the viewer directory from the lps/lps/utils directory and set allowRequestSOURCE=false in the Section 6.4, “WEB-INF/lps/config/lps.properties”.

Also note that source code to your applications may be made visible through the context ("right click") menu. See Chapter 31, Input Devices and Gestures for a discussion about how to disable this programmatically.

The server keeps track of the following loads:

The server also keeps track of the number of unique data and media urls that have been requested. You can toggle url details at run-time by using the durl=[0|1] and murl=[0|1] query string parameters for data and media urls, respectively. By default, url details are turned off. See lps.properties for more info.

The server-side configuration is different for different servlet containers and web servers. The idea is to tell whatever application responds to HTTP requests that it should compress JavaScript before sending it. We expect our users to deploy to a variety of servlet containers and web servers, so, instructions on how to configure a particular system to gzip JavaScript are beyond the scope of this document. We recommend that deployers do do this configuration. As an example, for tomcat, one would add attributes about compression to the connector tag in your server.xml:

<Connector port="8080"
compression="on"
compressionMinSize="2048"
noCompressionUserAgents="gozilla, traviata"
compressableMimeType="text/html,text/xml,text/JavaScript,application/x-JavaScript,application/JavaScript"/>

The client-side configuration is much easier; the HTTP protocol specifies "content codings" which may include gzip. A properly configured server will add the appropriate content-coding=gzip header, and modern browsers will recognize that that header means that the content will be gzipped. With todays browsers (including all browsers supported by OL4), this does not require any client-side (browser) configuration.