Deploying

Overview

Applications built with WaveMaker can be deployed to a number of environments, including local servers, public clouds, and private clouds. When you press 'Run' from the WaveMaker studio, you are deploying a web application that can be accessed by anyone on your network (e.g. by anyone inside your network firewall).

WaveMaker applications require a Java Web Server (for example: Tomcat, WebSphere, WebLogic, JBoss, GlassFish). When deploying to cloud solutions, WaveMaker will automatically provision servers that include a Java Container, managing the prerequisite dependencies.

The steps to deploy an application are:

1. Generate a WAR or EAR file
2. Create or identify a server where the application will run
3. Deploy the application to the server

Easy Workgroup Deployment

The easiest way to deploy a WaveMaker application is to press the Run button in WaveMaker Studio. When you press run from the WaveMaker studio, you are deploying a web application that can be accessed by anyone on your network (e.g., by anyone inside your network firewall).

Pressing run will run the application in a new browser window. The url for the application in the new browser will look something like this:

http://localhost:8094/EmployeeApp/login.html

Here are the elements of the generated url:

• localhost: this is the "generic" name for your computer on the network. For other users to access your application, you will need to replace "localhost" with your actual computer name.
• 8094: this is the port that is running the dedicated tomcat server that is used by WaveMaker studio.
• EmployeeApp: this is the name of your application, which is the same as the name of your WaveMaker project. You can change this by setting the "context root" parameter during the application deployment
• login.html: this is the default start page for applications with security enabled. If you are not using security, this will not be part of the url.

In order to make this application available to other users on your network, substitute the name "localhost" in the url with the actual name of your computer.

To find the name of your computer on windows, bring up the System Properties dialog by pressing the start button, then right-clicking on the "My Computer" icon and selecting "Properties". Next select the "Computer Name" tab and look at the "Full computer name property", which in this case is DB7K25C1.

To enable another user on the same network to access your application, just substitute the "localhost" name in your url with "DB7K25C1". In this case, the url would look like this:

http://DB7K25C1:8094/EmployeeApp/login.html

On another user's computer, your application will look like this:

Note: as long as your project is running in WaveMaker studio, it will be available to other users on your network. If you close the project or close Wavemaker studio, it will become unavailable.

Workgroup Deployment to a Dedicated Computer

Best practice: use one computer to edit WaveMaker applications and another computer to run a WaveMaker application that is accessible to other users in your work group.

The easiest way to run a deployed WaveMaker application is to install WaveMaker on a dedicated computer. Export your WaveMaker project as a Zip file (select the File menu, then select Export Project), then re-open the zip file in WaveMaker studio on the dedicated computer (unzip the exported project in the WaveMaker project directory and then select the File menu, then select Open Project) and press run. Now the application is deployed and running on the dedicated computer.

Note that this approach only allows you to run a single WaveMaker application on the dedicated computer. To run multiple WaveMaker applications on a dedicated computer, follow the steps for Workgroup Deployment for Multiple Apps.

Workgroup Deployment for Multiple Apps

Note: this documentation is for WaveMaker 6.1.10 and above.

If you want to deploy multiple applications to a single computer, you will need to follow these steps:

1. In WaveMaker studio, select File->Deployment
2. In the "Generate Application" accordion tab, select WAR file and press the "Generate Application" button. This step will take 3-5 minutes.
3. Now select the "Deploy to Servers" accordion tab and select "target 1" to deploy to the local tomcat server that is installed automatically with WaveMaker. Press the Edit button.
   
   
4. Change the port property to 8094. This is the port for the Tomcat installed by WaveMaker. Press the OK button. Next press the "Back to Server List" button.
   
   
5. With "target 1" selected in the Server List, press the OK button. Accept the default server information: host = localhost, port = 8094, username = manager, server = manager. Press the OK button.
   
   
6. WaveMaker displays a list of all the applications running on the localhost tomcat instance. Note that you can see the WaveMaker studio running as one of the applications. Now press the deploy button.
   
   
7. Enter the context root name for the running application. Note that this cannot be the same as the WaveMaker project name! A best practice is to give your WaveMaker project names version names such as EmployeeAppV1, then use EmployeeApp as the context name for deployment.
   
   
8. The application will now deploy (takes 1-2 minutes) and you will return to the list of applications running in the tomcat server. Once the application is deployed, you can close the project and the application will keep running - just be sure to keep the WaveMaker application launcher running!
   
   
9. To restart the application, close the WaveMaker launcher, restart the WaveMaker launcher, open the WaveMaker project file and repeat the steps (note that if the project has not changed, you do not have to re-generate the WAR file).

Generating a WAR / EAR File

WaveMaker Studio will generate a WAR (web application archive) and EAR (enterprise archive) file, which you can deploy on to any Java web server (for example: Tomcat, WebLogic, WebSphere, JBoss, GlassFish) running on JDK 1.5, or JDK 1.6.0_04 or above.

For the latest information on supported platforms and configurations for WaveMaker Studio development and deployment, see System Platforms.

To create a WAR and EAR file, follow these steps:

1. Open the project in WaveMaker Studio.
2. From the File menu select Deployment ....
3. Select the Generate Application accordion.
4. Press the Generate Application button. The WAR and EAR file are generated.
   Note:WAR and EAR generation will take a few minutes.
   
   Note: Studio records and displays the date of the most recent generation of the application. The date is visible at the top of the "Generate Application" accordion.

To deploy the application manually, download the WAR or EAR file by selecting either the WAR file or the EAR file from the list then pressing the Download Application button.
Note: if you are using the Desktop Studio, the WAR and EAR files are also available in the "dist" directory of your project.

JNDI (Java Naming and Directory Interface)

Advanced users only.

When generating the WAR (or EAR) file, WaveMaker allows you to configure the JNDI setting. To use this service, JNDI must be configured in your server environment. JNDI, is a directory service interface. If JNDI is not configured in your environment then do not check the JNDI box. Enterprises use JNDI to adjust DB specifics, including connection settings, without having to modify the applications that uses the DB.

The database must be reachable by the server when the application is executed. If you are deploying your app to a webserver, the db must be reachable by the webserver. This can be on the same host as the httpd/tomcat or not, but the server (tomcat) must be able to access the db. The DB connection may be different in production than in development. Be certain to update the connection settings BEFORE generating the WAR file.

JNDI Setup

Check Use JNDI the press the Setup JNDI button. In the dialog configure the JNDI Name for each datamodel in the application. WaveMaker will configure Spring (datamodelname.spring.xml) and the data model property file (datamodelname.properties) based on the information provide in the JNDI Setup dialog

By convention JDBC JNDI resource names are prefaced with "jdbc". A datasource named CustomerDB would then have the JNDI resource name "jdbc/CustomerDB". The JDNI Name to use in the JNDI Setup dialog would be "java:comp/env/CustomerDB"

For more information on JNDI, see the Java Documentation on JNDI.

Manage Cloud Servers

If you are not deploying to a cloud then proceed to the Deploy to Servers accordion. The Manage Cloud Servers accordion is used to manage cloud instances.

WaveMaker manages public or private cloud servers. You may view, create, and terminate cloud server instances and manage files stored on the cloud. You must have an account with one or more cloud provider to use this portion of the WaveMaker deployment functionality.

WaveMaker directly supports the following clouds:

• Amazon Elastic Compute Cloud (EC2)
• Eucalyptus
• OpSource Cloud
• RackSpace Cloud

Although each service provider requires unique information, the process used to manage cloud servers is similar for all clouds.

1. Select the cloud service provider.
2. Enter credentials to access the cloud. The specific credentials differ for each cloud. On Amazon, you can get to your Access Key and Secret Access Key by going to aws.amazon.com, selecting the "Account" menu and "Security Credentials" task. See below for details of other cloud providers.
3. Manage cloud instances. WaveMaker utilizes the credential to access the cloud provider and will provide a list of all servers configured for the account. From the interface you may create new servers, terminate existing servers, and manage file containers.
   
4. Select deployment targets. From the list of servers, select the deployment target that will execute or store the WaveMaker application. A deployment target allows you to quickly deploy (and redeploy) WaveMaker applications to that target. Deployment targets are not required to deploy a WaveMaker application.
   

Amazon Elastic Compute Cloud (EC2) Deployment

Getting Started with Amazon EC2

Before deploying a WaveMaker application to Amazon, you need to sign up for the Amazon EC2 service. This will take about 30 minutes.

Follow the Amazon "Getting Started" instructions by clicking Amazon EC2 getting started guide

This will guide you through the following steps:

1. Sign up for EC2
2. Launch instance - just launch a standard Fedora AMI (first option in the list)for now and terminate it when you are done signing up.
3. Create a key pair (.pem file)
4. Create a security group using that opens up HTTP on port 80 and SSH on port 22. For security, only allow your computer IP to access SSH port 22. This way, even if someone has your tomcat or MySQL passwords, they can't login.
5. Connect to your Linux instance - follow the instructions here for "Connecting from a Windows Machine", including creating a private key from your .pem file and connecting to your AMI instance via putty.
6. Terminate your instance

1. Go to aws.amazon.com, selecting the "Account" menu and "Security Credentials" task. This will display your access key.
2. Click on the Secret access key link to see your secret access key.

Make sure to store your .pem file and private key somewhere safe! For security purposes, the Access ID and Access Key are not stored within WaveMaker Studio. Each time you return to the Amazon portion of the Deployment screen you will be asked to provide the Access ID and Access Key.

Note: if you are using WaveMaker 6.0 or earlier, the default port is 8080.The port exposed in the Amazon security group must match the port number used when deploying the application.

If you do not open HTTP port 80 access in your default security group, deployment from studio will fail.

Choosing an AMI

In general, WaveMaker applications can be deployed to most any AMI running a supported Java application container such as tomcat using a supported JDK. The simplest configuration is running tomcat on port 80. More advanced configurations often use mod_proxy or mod_jk.

Access to the machine via ssh or remote desktop is strongly suggested and often needed for system configuration. Root access via a private key file is more secure than via password. Some windows AMI's do not provide administrator passwords and thus can not be accessed as administrator.

Alestic provides lists of the Canonical updated Ubuntu images for both ESB boot and instance store. ESB boot is required for micro instances. For those starting out, Ubuntu is generally more friendly than the average linux and Alestics images are a good starting place.

WaveMaker "1-Click" EC2 Deployment Example

1. Make sure that your database connection setting is updated to the username/password for MySQL on your AMI
2. In WaveMaker studio, go to File->Deployment. In the Generate Application accordion tab, generate the WAR file.
3. In the Manage Cloud Servers accordion tab, first enter your Amazon Access Key and Secret Access Key. 6.1 Note: if you enter the wrong credentials, you will have to restart studio and then re-enter your credentials - this bug will be fixed in 6.2.
4. Once your Amazon credentials have been accepted, press the "Create" button to create a server
   
5. In the "Create Server" screen, select the first Server Image AMI listed (this will be the most recent server image)
6. Next, select the Security Group you set up with HTTP port 80 and SSH port 22 open. Select a key pair for security. Choose an instance size - choose m1.small unless you need a lot of horsepower!
7. Press the "Create" button to start up your Amazon instance. You will get a popup that says "Creating an EC2 instance"
8. Once the deployment is complete, you will return to the server list and see your server running.
9. Select your application in the server list and press the "Add to Deployment Target Table" button.
10. When the "Server Properties" screen appears, enter a description for your application. Next, set up the Tomcat login information. For the latest WaveMaker AMI, the User is "manager" and the Password is "juhUFre5enu5".
    
    
11. Now open the "Deploy to Servers" accordion tab and select the server you just added from the list. Press the "OK" Button. This brings up the "Enter Server Information" screen. Set the port to 80 and re-enter the username and password login for Tomcat.
12. You will now see a list of the applications deployed on your Amazon instance. By default, you will see the SimpleSakila demo application and the Tomcat manager application running.
    
    
13. Press the "Deploy" button.
14. Enter the URL Context Root and Press "OK".
    The context root will be used in the URL of the deployed application. Deployment will take a few minutes.
    
    When the application has deployed WaveMaker returns to show the list of applications deployed on the server, including the newly deployed application.
15. Select the URL of the application to view it, running on Amazon
    

Amazon Simple Storage Service (S3) / RightScale

RightScale enables you to deploy, manage, and automate business-critical applications on the cloud. WaveMaker integrates with RightScale to simplify the effort. Once you have built an application and generated a WAR file you must make the WAR/EAR available to RightScale to deploy and manage. If the application will be deployed to Amazon then the WAR/EAR file must be uploaded to Amazon's Simple Storage Solution (S3). The steps required are:

1. Enter your Amazon Access Key and Secret Access key. (See Amazon Access Keys for details.)
2. Press OK
3. Choose or create a container (also known as an Amazon S3 bucket) where the WAR/EAR file should be stored.
4. Press Add to deployment targets table so the container will be readily available for future deployments.
5. Complete the form and press OK
6. Select the Deploy to Servers accordion tab
7. Press Refresh
8. Select the container deployment target you just created and press Deploy
9. Enter your Amazon Access Key and Secret Access key
10. Press OK
11. Press Upload WAR or Upload EAR, depending on which application artifact you will use with RightScale. In most cases WAR files are used.
12. Login to RightScale and configure the deployment scripts.

Other Cloud Provider Deployment

Eucalyptus Cloud

OpSource

RackSpace Servers

The RackSpace documentation is incomplete. Please return shortly for updated documentation.

To deploy to RackSpace Servers you will need:

• A RackSpace - see http://www.rackspacecloud.com to create an account
• The RackSpace Username and Password (API Access Key) for your account
• Other Stuff - to be documented To Be Documented

RackSpace Username and API Access Key

The RackSpace APIs used by WaveMaker required the Username and API Access Key. WaveMaker uses the APIs to provide deployment services, including:

• create new cloudservers
• terminate couldservers
• list the available cloudservers for your account

Server Image

High level server description

Server Flavor

This plays the similar role of "images" in other service provider.

Once a server is created, an email is sent from RackSpace that includes the details about the server and the root password.

RackSpace Storage / RightScale

RightScale enables you to deploy, manage, and automate business-critical applications on the cloud. WaveMaker integrates with RightScale to simplify the effort. Once you have built an application and generated a WAR file you must make the WAR/EAR available to RightScale to deploy and manage. If the application will be deployed to RackSpace then the WAR/EAR file must be uploaded to RackSpace's cloudfiles. The steps required are:

1. Enter your RackSpace credentials. (See RackSpace Username and API Access Key for details.)
2. Press OK
3. Choose or create a container where the WAR/EAR file should be stored.
4. Press Add to deployment targets table so the container will be readily available for future deployments.
5. Complete the form and press OK
6. Select the Deploy to Servers accordion tab
7. Press Refresh
8. Select the container deployment target you just created and press Deploy
9. Enter your RackSpace credentials
10. Press OK
11. Press Upload WAR or Upload EAR, depending on which application artifact you will use with RightScale. In most cases WAR files are used.
12. Login to RightScale and configure the deployment scripts.

Java Web Server Deployment

Web.xml entries

The web.xml file in a project webapprootWEB-INF folder is managed by studio and should not be edited directly.
Web.xml customizations should be placed in webapprootWEB-INFuser-web.xml. The contents of user-web.xml will be merged with the contents of web.xml for deployment.

Tomcat Deployment

When deploying to Tomcat, there are a few tips that may help you get the most out of your WaveMaker application. Most of Tomcat's defaults are fine for standard web applications, including WaveMaker.

Memory

If you have several WaveMaker applications deployed to a single machine, you might need to increase both Java's heap size and the amount of permgen space. By default, both are set at 64 megabytes. It is difficult to measure exactly how much of each an individual application may take, as resource usage varies heavily depending on the application.

WaveMaker recommends 20m of permgen and 30m of heap per application, but this varies by application and load. At absolute minimum, for each application you should have 5605k of heap and 9344k of permgen. Heap usage in particular will increase with load, so be sure to provide plenty.

To increase Java's memory usage, see below. Recommended settings (and the defaults) are:

• Heap is set with -Xmx128m (increasing the maximum to 128 megabytes)
• permgen is set with -XX:MaxPermSize=400m (increasing the maximum to 400)

Editing Tomcat JVM settings

The following describes editing the JVM settings for the embedded Studio Tomcat.
To adjust tomcat JVM settings for standalone tomcat installations, see a Tomcat guide such as this one by Atlassian

Edit the file /applications/wavemaker.app/Contents/MacOS/wmstart.sh

Edit the start command to pass th "-Xmx" property to the JVM. For example to set the max memory to 512 MB, use " -Xmx512m"

To increase the max heap size:

1. Open the WaveMaker start menu item
   1. Start Menu -> WaveMaker -> Version -> WaveMaker
      
2. Right click on WaveMaker
3. Select Properties
4. Edit the Target value
   Note, you will need to scroll within the target field to see the JVM options.
   

Server Status

To monitor the current JVM Max Heap Size setting and memory usage, go to the tomcat status page

http://localhost:8094/manager/status

Here is example output of a Tomcat status with the max heap size set to 400m

Log Rotation

By default, WaveMaker applications log everything to stdout. Tomcat redirects this to a log file, but the log file will grow without bounds. Log rotation is the recommended way to solve this, but you'll have to change the log appender from stdout to a file.

Your project's log4j.properties (located in the src directory) may have a header like:

log4j.rootLogger=warn, stdout
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d %p &#91;%c&#93; - <%m> (%x) %n

or

log4j.rootLogger=warn, stdout, wmlog\\log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d %p &#91;%c&#93; - <%m> (%x) %n

# default catalina.home; when the System property isn't set, this will be
# used
catalina.home=.
log4j.appender.wmlog=org.apache.log4j.RollingFileAppender
log4j.appender.wmlog.File=${catalina.home}/logs/wm.log
log4j.appender.wmlog.MaxFileSize=10MB
log4j.appender.wmlog.MaxBackupIndex=10
log4j.appender.wmlog.layout=org.apache.log4j.PatternLayout
log4j.appender.wmlog.layout.ConversionPattern=%d %p &#91;%c&#93; - <%m> (%x) %n

You should remove the stdout entries, and add wmlog entries if they do not exist. The logger entries (following the above snippets) can be left unchanged. For example:

log4j.rootLogger=warn, wmlog
log4j.appender.wmlog=org.apache.log4j.RollingFileAppender
log4j.appender.wmlog.File=${catalina.home}/logs/wm.log
log4j.appender.wmlog.MaxFileSize=10MB
log4j.appender.wmlog.MaxBackupIndex=10\\log4j.appender.wmlog.layout=org.apache.log4j.PatternLayout
log4j.appender.wmlog.layout.ConversionPattern=%d %p &#91;%c&#93; - <%m> (%x) %n

The ${catalina.home} variable only exists in Tomcat. Other application servers may have similar settings.

Enabling GZIP Compression

Note: WaveMaker 6.1 Automatically GZIPs JavaScript files.

The WaveMaker client libraries are several large JavaScript files. Large files load faster than multiple small files, and further gains can be realized by enabled GZIP compression on the server-side. This will compress the files before they are sent; modern browsers can uncompress these on the fly.

To enable this, edit the Tomcat server.xml, and add the following lines to your Connector configuration:

compression="on" compressionMinSize="2048"
noCompressionUserAgents="gozilla, traviata, *?MSIE 6.*?"
compressableMimeType="text/html,text/xml,text/javascript,text/css"

For example, the Connector configuration might look like this:

<Connector port="8094" maxHttpHeaderSize="8192"
URIEncoding="UTF-8" maxThreads="150" minSpareThreads="25"
maxSpareThreads="75" enableLookups="false"
redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"
compression="on" compressionMinSize="2048"
noCompressionUserAgents="gozilla, traviata, .&#42;?MSIE 6.&#42;?" compressableMime Type="text/html,text/xml,text/javascript,text/css" />

Using APR native libraries

The APR native libraries will provide general performance improvements to Tomcat. This includes major improvements to serving static files directly, crypto/SSL speed, as well as some improvements to AJP connections to Apache httpd.

Using APR might disable GZIP compression. In situations with many clients connecting simultaneously, APR may have advantages, but in most situations GZIP compression will provide a better client experience, so WaveMaker recommends either using only GZIP compression (Enabling GZIP Compression), or APR and Apache httpd (Serving Static Content with Apache httpd).

For more information and downloads, consult Tomcat's documentation:

• For Tomcat 5.5: http://tomcat.apache.org/tomcat-5.5-doc/apr.html
• And Tomcat 6: http://tomcat.apache.org/tomcat-6.0-doc/apr.html

Serving Static Content with Apache httpd

In cases where APR native libraries don't provide enough of a performance boost, or if you want an additional layer between client and appserver, you can use Apache httpd. The Apache httpd server can be configured to respond to all requests; static files are served directly, and requests for Java resources are forwarded to Tomcat for processing. Apache httpd also handles SSL processing and GZIP compression.

You will need an Apache httpd server set up, and you should be familiar with Apache httpd configuration before attempting this.

Tomcat side configuration:

For Tomcat 5.5:

http://tomcat.apache.org/tomcat-5.5-doc/config/ajp.html

And Tomcat 6:

http://tomcat.apache.org/tomcat-6.0-doc/config/ajp.html

For Apache httpd, you should use either mod_jk:

http://tomcat.apache.org/connectors-doc/

or mod_proxy_ajp: http://httpd.apache.org/docs/2.2/mod/mod_proxy_ajp.html

Configuration information is available at those sites.

Deploying on WebLogic 10

WaveMaker's JSON runtime requires commons-lang-2.3.jar, however WebLogic uses an older version of commons-lang.jar.

To fix this, you will have to edit the setDomainEnv.cmd file (on Linux, this file is called setDomainEnv.sh) to set the PRE_CLASSPATH variable to use the commons-lang-2.3.jar.

For example:

PRE_CLASSPATH=%PRE_CLASSPATH%;C:worklibcommons-lang-2.3.jar

If you don't make this change, you'll see an exception that looks something like this:

java.lang.NoSuchMethodError: join
at com.wavemaker.runtime.server.json.JSONMarshaller.getPropertyName(JSONMarshaller.java:470)
at com.wavemaker.runtime.server.json.JSONMarshaller.handleObjectInternal(JSONMarshaller.java:395)
at com.wavemaker.runtime.server.json.JSONMarshaller.handleObject(JSONMarshaller.java:323)
at com.wavemaker.runtime.server.json.JSONMarshaller.doMarshal(JSONMarshaller.java:280)
at com.wavemaker.runtime.server.json.JSONMarshaller.marshal(JSONMarshaller.java:150)
at com.wavemaker.runtime.server.json.JSONMarshaller.marshal(JSONMarshaller.java:127)

See also: Tomcat in Dev

Build and Deploy Using Scripts

BatchBuild is a set of scripts to build, deploy, and undeploy WaveMaker projects. The scripts can be integrated into automated build process and do not require a running WaveMaker Studio.

The scripts are provided in the WaveMaker installation in the <WM-Install-Dir>/Support/Batchbuild director. The three scripts are:

• build.bat
• deploy.bat
• undeploy.bat

To use the scripts, update the included infrastructure to reflect the WaveMaker installation, specifically:

1. app-deploy.properties
   • project.dir - change the value to the location of your WaveMaker projects.
   • deploy.name - change the value to the name of the deployed project.
   • studio.webapproot - replace "WM" with the location of the WaveMaker installation. (The Windows default is "C:/Program Files/WavemMaker/6.1.9GA"
   • war.file.name - replace "myproject" with the name of the project to be managed
   • ear.file.name - replace "myproject" with the name of the project to be managed
   • orig.proj.dir - replace "myproject" with the name of the project to be managed
   • build.app.webapproot - replace "C:/wavemaker" with the location of your WaveMaker projects directory and replace "myproject" with the name of the project to be managed
   • wavemaker.home - change the value to the location of your WaveMaker projects
   • tomcat.manager.username - change the value to the username of the Tomcat manager
   • tomcat.manager.password - change the value to the password of the Tomcat manager
2. deploy.bat, build.bat, and undeploy.bat
   • Change "WM" to the location of the WaveMaker installation.

See Also

• Developer's Documentation - Deployment