Deploying ActiveGrid Applications

Deploying ActiveGrid Applications
This chapter contains the following sections:
Deploying Applications
To deploy an ActiveGrid Application, perform these two steps:
1.
In the ActiveGrid Studio, run the Deployment Wizard. This wizard creates the configuration files that you need for deployment, and then transfers the application files over to the ActiveGrid Server (Running the Deployment Wizard).
Note: These are the files used at runtime. Leave these files on the ActiveGrid Server, even after you deploy the application.
2.
Running the Deployment Wizard
To deploy an ActiveGrid Application, follow these steps:
1.
In the ActiveGrid Studio, open the project you want to deploy and select the Deploy Application... option from the Tools menu. This launches a deployment wizard to walk you through the steps to deployment.
2.
The first screen is the Choose an Application to Deploy screen. Select the project you want to deploy and click Next.
3.
The Choose Files to Deploy screen appears. Select the files that you want to deploy. You typically choose to deploy all the files in the project. If you choose to deselect a file, make sure it is not referenced by another file in the project. Click Next.
4.
The Deployment Options screen appears:
Session Persistence: Select your Session Persistence model (“Choosing a Session Persistence Model” on page 45). If you choose Database, you also need to select a data source.
Configure deployment data sources: If you used a test database for your development process, this is where you switch over to the database that you plan to use for the deployed application. For each Data Model file, you can select the appropriate data source.
Click Next. The Deployment Method screen appears.
5.
On the Deployment Method screen, choose a method for copying the project files over to the ActiveGrid Server. You can choose to transfer the files onto a mounted directory or using FTP.
If you want to use a different method to transfer the files, see Copying the Project Files Without FTP or a Mounted Directory.
6.
Click Next. The final screen depends on the deployment method you selected:
If you chose to use a mounted directory, the Deployment Path screen appears. Browse to the directory where you want to put the project files (Where to Put the Files).
If you chose FTP, the FTP Deployment screen appears. Type in the requested information for the FTP transfer and click Finish.
The wizard creates all the files you need for the deployed application and puts them in the location you specified on the ActiveGrid Server. To complete the deployment, run the deployment script on the server (Running the Deployment Script).
Copying the Project Files Without FTP or a Mounted Directory
In order to deploy an ActiveGrid application, you need to transfer all the project files from the development machine to the ActiveGrid Server. The deployment wizard does this for you either as an FTP transfer or by using a mounted fileshare.
If you prefer to transfer the files by some other means, then select the mounted directory option from the deployment wizard. For the deployment path, specify a local directory rather than a mounted remote directory. Finish the deployment wizard, then copy the entire contents of the local directory over to the ActiveGrid Server. Run the deployment script on the server to complete the deployment.
Running the Deployment Script
Before running the deployment script on the ActiveGrid Server, you must first create the deployment files for the project by running the deployment wizard in the ActiveGrid Studio (Running the Deployment Wizard).
To complete the deployment, you run the deployment script (called activegrid_deploy) on the ActiveGrid Server. The deployment script generates the Apache configuration file used for application deployment.
To run the deployment script, follow these steps:
1.
INSTALL_DIR/bin/activegrid_deploy -f INSTALL_DIR/local/deployments/YOUR_PROJECT/YOUR_PROJECT.dpl -r APPROOT
where:
INSTALL_DIR is the root directory of your ActiveGrid Server installation. Be sure to use the full path, rather than a relative path.
YOUR_PROJECT is the name of your project directory.
YOUR_PROJECT.dpl is the deployment file for the project.
APPROOT is the application root for your project. After you deploy your project, your application will be available to users at:
http://host:port/APPROOT
If you do not use the -r flag to specify an application root, the application will be available at:
http://host:port/YOUR_PROJECT
The activegrid_deploy script generates the Apache configuration (.conf) file that the ActiveGrid Server uses for application deployment.
2.
INSTALL_DIR/bin/activegridctl restart
On startup, Apache automatically loads all the configuration files located in the INSTALL_DIR/local/deployments directory, including the configuration file for your new application. The activegrid.conf loaded by Apache automatically load demoapp.conf and any other .conf files located in the INSTALL_DIR/local/deployments directory.
Where to Put the Files
The default location for deployed applications is in the INSTALL_DIR/local/deployments directory on the ActiveGrid Server. However, you can put your deployed applications anywhere on the server machine.
Note: These are the files used at runtime. Leave these files on the ActiveGrid Server, even after you deploy the application.
Testing Your Deployment
Ensure that Apache is working properly. Try URLs that worked before the deployment. If this is a new installation of Apache, or if the document root and subdirectories are new, simply try looking up the ActiveGrid Server welcome page:
http://myhost:myport/
Navigate to the application you just deployed. For example, for the PetStore demo, you use:
http://myhost:myport/petstore
Make sure the application behaves as expected. If the application stores data in the HTTP session, check that this data is correctly saved and recovered.
Undeploying an Application
To use the deployment script to undeploy an application:
1.
INSTALL_DIR/bin/activegrid_deploy -u INSTALL_DIR/local/deployments/YOUR_PROJECT/YOUR_PROJECT.conf
where:
INSTALL_DIR is the root directory of your ActiveGrid Server installation.
YOUR_PROJECT is the name of your project directory.
YOUR_PROJECT.conf is the configuration file for the project.
2.
INSTALL_DIR/bin/activegridctl restart
The script option removes the .conf file for the application. On startup, Apache automatically loads all the configuration files located in the INSTALL_DIR/local/deployments directory.
activegrid_deploy Script Usage
The following table lists the arguments that you can use with the activegrid_deploy script.
 
Optional. Name of the application base URL. After deployment, the application will be available at http://host:port/approot. If not set, defaults to the name of the deployment (.dpl) file.
Optional. By default, the script will point to the ActiveGrid configuration in INSTALL_DIR/local/deployments, but can be overridden by the user to point to another directory.
Undeploys an application, removing its configuration file. Must specify the name of the deployment to undeploy (deploymentname). Corresponds to a .conf file in the deployments directory. The script makes a copy of the configuration (.conf) file to a backup name.
-h
Password Encryption in ActiveGrid Deployment Files
The deployment wizard encrypts the data source passwords in the .dpl and .xacml files. It creates a file, called .agkeystore, that contains the encryption key. The .agkeystore file is located in the project directory.
ActiveGrid's password encryption uses a combination of XOR and MD5 to encrypt passwords in the .dpl and .xacml files. In order to retrieve the actual password, you need the following information:
By eliminating plain text passwords in the .dpl and .xacml files, we reduce the risk of unauthorized access to those files. However, if you prefer, you can use plain text passwords, rather than encrypted passwords, in the .dpl and .xacml files. To do this, edit the deployment file directly, deleting the encrypted passwords and replacing them with the plain text passwords.
Note: Even with password encryption, it is still necessary to safeguard your .dpl, .xacml and .agkeystore files with the appropriate file permissions.
About the Deployment File (.dpl)
The deployment file (.dpl) provides the information that the ActiveGrid Server needs in order to correctly deploy your application. This includes where to find the files that comprise your application, how to get to any necessary databases, and basic configuration information for the application as a whole.
Deployment files (.dpl), like other ActiveGrid files, are XML files. The following table lists the elements that appear in an ActiveGrid deployment file. Each element is described in more detail in the following sections, along with their respective child elements, if any.
 
The parent element for the other elements in the deployment file. Specifies information about the deployment, including session information.
Identifies a service (such as Web services, local services, or database services) being used by the application (.wsdl file).
Identifies an XForm (.xform) being used by the application. The deployment file contains one xFormRef element for each XForm in the application.
Identifies the static directory for the application. This is the directory that contains the images and other static content for the application.
The Deployment Element
The deployment element encloses the other elements that comprise the deployment file. The <ag:deployment> element is the first element in the deployment file after the <?xml> declaration and it includes the name space declarations for the file, along with some global settings for the deployment. Here’s an example:
<?xml version="1.0" encoding="utf-8"?>
<ag:deployment
xmlns:ag="http://www.activegrid.com/ag.xsd"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
sessionPersistence="EXTERNAL"
sessionTimeout="1800"
sessionCleanupInterval="60"
PageFrame="PageFramexform/PageFrame"
beginOperation="petstore/begin/default"
signonForm="SignOnxform/SignOn"
externalPackage="petstore"
setupOperation="petstore/PetstorePortType/initSession"
version="10">
The last line in the .dpl file is the closing tag for the deployment element:
</ag:deployment>
The following table lists the available attributes for the deployment element. All the other elements in the deployment file are child elements of the deployment element. These elements are discussed in the following sections.
 
How often the session table is purged of expired sessions. Specifies the number of seconds between expired session cleanups. Used for sessionPersistence type of “DATABASE”.
Identifies the dataSource element used to store sessions for sessionPersistence type of “DATABASE”.
Sets the number of servers in the cluster on which to replicate the session. Default is zero.
Specifies the number of seconds after which an inactive session will be expired and subject to removal from the database.
Name of the session-initialization operation. Called once per session. Format is serviceName/portType/operation.
Name of an xform the application uses to force the user to log on before going to pages that require authentication.
The ProcessRef Element
The processRef element identifies the process file (.bpl) for the application. It has the following attributes:
 
A string specifying the pathname of the file containing the process model. The pathname is relative to the application deployment directory (the directory that contains the deployment file).
The SchemaRef Element
The schemaRef element identifies a schema being used by the application. It has the following attributes:
 
A string specifying the pathname of the file containing the schema. The pathname is relative to the application deployment directory (the directory that contains the deployment file).
The schemaRef element has a sub-element, called datasourcename.
 
The ServiceRef Element
The serviceRef element identifies a service being used by the application. It has the following attributes and elements:
 
A string specifying the pathname of the Web Services Definition Language (.wsdl) file describing the operations supported by this service and messages they use. The pathname is relative to the application deployment directory (the directory that contains the deployment file).
A string identifying the type of service or protocol used. The value must be one of the following: “SOAP”, “REST”, “RSS”, “LOCAL” or “DATABASE”.
The serviceref has the following elements:
 
A required element when the serviceType is “LOCAL”; identifies the location of the module and/or class used to implement the service. The class name is named in a “className” attribute of this element. This element only appears when the serviceType is “LOCAL”.
A required element when the serviceType is “RSS”; defines connection attributes of the RSS or Atom feed.
For “LOCAL” services, optional elements specifying “name” and “value” attributes providing input values for an operation’s parameters. serviceParameters are designed to provide default or fixed input values for parts of a request. Multiple serviceParameters may be specified.
For “SOAP” and “REST” services, optional elements specify default values for parts of an input message. The “message” attribute refers to an input message of the service and the “part” attribute is the name of a part within that message. The “value” element specifies the default value.
ServiceRef Child Elements: The restService Element
The restService element is a required child element of the serviceRef elements when the serviceType attribute is set to “REST”. It describes connection attributes of the REST Web service. The restService element has the following attribute:
 
The base URL of the REST service. Parameters from input messages are appended to this URL as path segments (e.g. “/parts/00345”) or query parameters (e.g. “?id=42”)
ServiceRef Child Elements: The rssService Element
The rssService element is a required child element of the serviceRef element when the serviceType attribute is set to “RSS”. It describes connection attributes of the RSS or Atom feed. The rssService element has the following attributes:
 
A string identifying the protocol version of the feed. Supported versions are “RSS-0.91”, “RSS-2.0”, “Atom-0.3”, and “Atom-1.0”.
ServiceRef Child Elements: The localService Element
The localService element is a child of the serviceRef element when the serviceType attribute is set to “LOCAL”. Operations in Local services may be implemented by either global functions or class functions.
This element identifies the location of the module and class used to implement the service. The localService element has the following attributes:
 
For Local services implemented by a class, the name of that class (in the source file specified by “fileName”). Note that if this attribute is not present, the local service is assumed to be implemented by global functions.
The SkinRef Element
The skinRef element identifies a skin file (.skn) in use by the application. Only one skin and skinRef are permitted per application. The skinRef element has the following attributes:
 
A string specifying the pathname of the file containing the skin. The pathname is relative to the application deployment directory (the directory that contains the deployment file).
The XFormRef Element
The XFormRef element identifies a Page (.xform file) in use by the application. Any number of XFormRef elements are permitted. The XFormRef element has the following attributes:
 
A string specifying the pathname of the file containing the XForm. The pathname is relative to the application deployment directory (the directory that contains the deployment file).
The DataSource Element
The dataSource element defines the connection parameters for a database. The dataSource element has the following attributes:
 
A string identifying the database vendor. Legal values are: “MySQL”, “Oracle”, “PostgreSQL”, “DB2” and “SQLite”.
An integer identifying the number of connections to keep open to the database. The default is 30.
A string by which this datasource can be referenced (e.g. the datasourcename element of a schemaRef element will specify this).
The dataSource element has the following child elements:
 
A string containing a platform and database specific value. These values identify the database server instance.
Here is an example:
<ag:datasource name="petstore-datasource" dbtype="MySQL" maxPooledConnections="40">
<ag:database>testdb1</ag:database>
<ag:dsn>127.0.0.1:3306</ag:dsn>
<ag:password>activegrid</ag:password>
<ag:username>activegrid</ag:username>
</ag:datasource>
The staticDir Element
The staticDir element contains the path to the root directory of application static files. The pathname is relative to the application deployment directory (the directory that contains the deployment file). For example:
<ag:staticDir>static</ag:staticDir>
The rbacPlugin Element
The rbacPlugin element contains the path to a custom authentication module, if you have one. For example:
<ag:rbacPlugin>petstore/RBACPlugin</ag:rbacPlugin>
Example Deployment File
This section contains an example deployment file with comments.
<?xml version="1.0" encoding="utf-8"?>
<ag:deployment
xmlns:ag="http://www.activegrid.com/ag.xsd"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
pageFrame="PageFramexform/PageFrame"
beginOperation="petstore/begin/default"
signonForm="SignOnxform/SignOn"
setupOperation="petstore/PetstorePortType/initSession"
version="11"
sessionPersistence="DISTRIBUTED"
sessionDataSource="petstore-SQLite"
sessionRedundancy="1"
>
<ag:datasource name="petstore-SQLite" dbtype="MySQL" maxPooledConnections="1">
<ag:database>testdb2</ag:database>
<ag:dsn>127.0.0.1:9200</ag:dsn>
<ag:password>activegrid</ag:password>
<ag:username>activegrid</ag:username>
</ag:datasource>
<ag:identityref name="petstore" filePath="petstore.xacml"/>
<ag:processref name="petstore" filePath="petstore.bpel"/>
<ag:schemaref name="petstore.xsd" filePath="petstore.xsd"/>
<ag:serviceref name="petstore" filePath="petstore.wsdl" serviceType="LOCAL" stateful="False" version="11">
<ag:localService fileName="petstore.php" processName="petstore"/>
</ag:serviceref>
<ag:skinref name="petstore" filePath="petstore.skn"/>
<ag:staticDir>static</ag:staticDir>
<ag:xformref name="accountDetailxform" filePath="xforms/accountDetail.xform"/>
<ag:xformref name="accountEditxform" filePath="xforms/accountEdit.xform"/>
<ag:xformref name="accountInsertxform" filePath="xforms/accountInsert.xform"/>
<ag:xformref name="accountListxform" filePath="xforms/accountList.xform"/>
<ag:xformref name="accountSearchxform" filePath="xforms/accountSearch.xform"/>
<ag:xformref name="Cartxform" filePath="xforms/Cart.xform"/>
<ag:xformref name="Categoryxform" filePath="xforms/Category.xform"/>
<ag:xformref name="CheckOutxform" filePath="xforms/CheckOut.xform"/>
<ag:xformref name="HomePagexform" filePath="xforms/HomePage.xform"/>
<ag:xformref name="Itemxform" filePath="xforms/Item.xform"/>
<ag:xformref name="OrderCompletexform" filePath="xforms/OrderComplete.xform"/>
<ag:xformref name="Productxform" filePath="xforms/Product.xform"/>
<ag:xformref name="Searchxform" filePath="xforms/Search.xform"/>
<ag:xformref name="SignOnxform" filePath="xforms/SignOn.xform"/>
<ag:xformref name="SignedOffxform" filePath="xforms/SignedOff.xform"/>
<ag:xformref name="PageFramexform" filePath="xforms/PageFrame.xform"/>
</ag:deployment>
 

ActiveGrid
Installation and Deployment Guide
Version 2.0