This is documentation for Apprenda 7 and 8.
Documentation for newer version is available at https://new.docs.apprenda.com.

Load Files into the Application Server/Container for Java Web Application Workloads

Using an Application Bootstrap Policy, a Platform Operator can load application files (such as jars, JBoss modules, properties files, configuration files, etc.) in the deployment of the Tomcat and JBoss containers upon which Java Web Application workloads (WARs) are deployed. This functionality provides support for scenarios such as the following:

  • applications that require additional jars or files to be loaded by the container/application server 
  • changes to the base of the container/application server through config file modifications

It should be noted that this functionality is not supported for Linux Services, Docker, or WebSphere workloads at this time.

Creating a custom platform-mods bootstrapper

A platform-mods bootstrapper ZIP file should be created according to the requirements outlined in the Custom Bootstrapper Tutorial. In addition to the requirements listed in the tutorial, the ZIP file should also contain a directory called platform-mods that contains the items that should be copied to the Tomcat or JBoss container.

The developer-created DLL included in the bootstrapper ZIP file should contain a Bootstrapper implementation that will copy the platform-mods folder to a location that is next to the artifact (in this case, the WAR file) when it is bootstrapped. When the workload is then deployed on a Linux Server, the contents of the platform-mods folder will be copied to the base application server configuration. Therefore the file structure within the platform-mods folder should mirror the structure in which the folders and their contents should be copied relative to the container's root.

The attached Grails_Bootstrapper_Debug.zip is a sample platform-mods bootstrapper designed to support running an application called JBilling on the Apprenda Platform. JBilling is a Java web app developed using the Grails web app framework; when using JBilling's default configuration, it requires that additional directories be placed in Tomcat's root directory. The directory structure in the platform-mods folder within the ZIP file represents the structure of what must be copied to the root of the Tomcat container in order to provide the required directories needed to support JBilling. 

While the contents of the platform-mods folder is specific to JBilling, the PlatformModsTestBootstrapper.dll file included in the Grails_Bootstrapper_Debug.zip is not; it is instead a generic bootstrapping implementation that will copy the platform-mods folder to a location next to the artifact when it is bootstrapped. Because of this, this DLL may be reused in other bootstrappers; simply replace the contents of the platform-mods folder with the structured content required by a given implementation in order to create a new custom platform-mods bootstrapper.

It should be noted that there are no restrictions on the directory or file names that can be included in the platform-mods folder: all files and folders will be copied. In all cases, additive changes will be allowed. The behavior when the copied files already exist is dependent on the container type. A description of this behavior and other container-specific information can be found below. 

Tomcat

For Tomcat, if any of the copied files already exist, they will be overwritten with the files included in the platform-mods directory (and the Platform will issue a warning). For instance, if the bootstrapper includes a server.xml file (typically at platform-mods/conf), its contents will overwrite any existing configuration. It is therefore important that the any configuration files included in the bootstrapper are correct; otherwise workloads will fail to deploy.

Should you include any jars that will be used from the application, the classloader whitelist (as determined by the Hosting.Linux.TomcatClassLoaderDelegateList setting in the Platform Registry) should be updated accordingly; however, if the jar will be used by the application server, there is no need to update the classloader whitelist.

JBoss

For JBoss, modules included in the bootstrapper (typically located in platform-mods/modules) should be additive only. Each module must be a valid JBoss module with a correct directory structure and corresponding module.xml file, and must include all jar files defined in the module.xml file. More than only module may be included in the platform-mods/modules directory.

Should the bootstrapper include a standalone.xml file (located at platform-mods/configuration), when a Java Web Application is deployed and bootstrapped, the standalone.xml file will be merged into the apprenda-standalone.xml file that ships with Apprenda and defines default JBoss configuration on the Platform.

The standalone.xml file included in the  bootstrapper will be checked with xml namespace. If the check fails, an exception will be thrown and logged, and there will be no merge at all. If the check passes but the standalone.xml file is otherwise invalid, workload deployment will fail.

If the merge is successful, each part of the configuration file will be processed in one of three ways depending on how the Platform recognizes the specific section:

  • merging is not allowed: the sections will be discarded if they exist in standalone.xml file
  • merging is allowed: additive information will be merged in (but nothing will be overwritten)
  • the section will be overwritten: information from the standalone.xml file will overwrite that in the apprenda-standalone.xml file

Below are JBoss configuration sections for which merging is not allowed :

  • <interfaces/>
  • <socket-binding-group/>
    (Note: because merging is not allowed for <socket-binding-group/>, it is not possible to create <socket-binding />; as a result, any customization of JBoss that depends on socket-binding is not supported.)
  • <security-realms/> within <management>
  • <management-interfaces/> within <management>
  • <access-control/> within <management>
  • <connector> tags into the urn:jboss:domain:web subsystem

The following are JBoss configuration sections for which merging is allowed::

  • <extensions/>
  • <system-properties/>
  • <paths/>
  • <profile/>
  • <audit-log/> within <management>

<subsystem/> within <profile/> will be merged differently according to their category:

  • Subsystems for which merging is not allowed:

    • urn:jboss:domain:logging 
  • Subsystems that will be overwritten 
    • urn:jboss:domain:jacorb
    • urn:jboss:domain:jgroups
    • urn:jboss:domain:jpa
    • urn:jboss:domain:jsf
    • urn:jboss:domain:mail
    • urn:jboss:domain:messaging
    • urn:jboss:domain:naming
    • urn:jboss:domain:resource-adapters
    • urn:jboss:domain:threads
    • urn:jboss:domain:weld
    • urn:jboss:domain:jaxrs
    • urn:jboss:domain:jdr
    • urn:jboss:domain:pojo
    • urn:jboss:domain:sar
  • Subsystems for which merging is allowed:
    • urn:jboss:domain:datasources
    • urn:jboss:domain:deployment-scanner
    • urn:jboss:domain:ee
    • urn:jboss:domain:infinispan
    • urn:jboss:domain:jca
    • urn:jboss:domain:jmx
    • urn:jboss:domain:remoting
    • urn:jboss:domain:security
    • urn:jboss:domain:transactions
    • urn:jboss:domain:web
    • urn:jboss:domain:webservices

Creating an Application Bootstrap Policy with the custom platform-mods bootstrapper

In order to upload a platform-mods bootstrapper to the Platform, you must create an Application Bootstrap Policy using the bootstrapper ZIP file; this will configure the Platform to bootstrap the contents of the platform-mods folder into newly deployed Tomcat or JBoss containers. In some situations, it may be appropriate to apply the Bootstrap Policy to all Java Web Application workloads deployed on the Platform (e.g., if only Tomcat is supported and the policy simply extends a timeout in the standard server.xml configuration). In many cases, however, the contents of a platform-mods bootstrapper are not appropriate for all Java Web Application deployments. In such cases, it is necessary to apply the Bootstrap Policy only in certain situations; this can be done by making the Bootstrap Policy conditional on the value of a set Custom Property.

In the example below, a Custom Property is created that allows developers to select whether or not to run the Grails_Bootstrapper_Debug.zip bootstrapper when deploying Java Web Application workloads; the Custom Property is then used in the Conditions section of the Application Bootstrap Policy by which the Grails_Bootstrapper_Debug.zip is configured. Because the bootstrapper is applicable only to a specific application running on Tomcat, the default value for the Custom Property is configured so that by default the bootstrapper will not run. Developers deploying an application such as JBilling simply update the value of the Custom Property before deploying JBilling on the Platform, which will result in the bootstrapper's execution when the Java Web Application is deployed.

Sample Platform configuration 

Create the following Custom Property:

Sample Custom Property
General Settings  
     Name GrailsForJBilling
     Display Name Grails for JBilling
     Description Add directories to the Tomcat container that are necessary to deploy JBilling.
     Allowed Values Yes,No
     Applies to: Applications (Allow Multi-Select=no/unchecked)
Default Value(s) No
Application Settings  
     Scope Application Component Level: Java Web Applications
     Developer Visibility  
          Visible to Developers Yes
          Required for Deployment No
          Editable by Developers Yes

Create the following Application Bootstrap Policy

Sample  Bootstrap Policy
General Settings  
     Name Grails for JBilling Bootstrapper
     Description Add directories to the Tomcat container that are necessary to deploy JBilling.
     Active Policy Yes
     Applies to Linux Application Components
     Application Stage Sandbox
Published
Bootstrap Libraries Run a custom workflow for deployments using the
Grails_Bootstrapper_Debug.zip file.
Conditions Bootstrap only if the component being deployed satisfies
     Component Type Java Web Applications
     Custom Property Increase Tomcat Timeout (or whatever you named the
Custom Property you created according to the
directions above)
     Comparison Logic Contain All
     Value(s) Yes

Once created, the above configuration will allow developers to apply the bootstrapper to Java Web Application components at their discretion by setting the value of the Increase Tomcat Timeout (or alternately named) Custom Property to Yes for the component in the Developer Portal.

The above Custom Property and Application Deployment Policy configuration may be used for your own platform-mods bootstrapping implementation; simply update the Name, Display Name (for the Custom Property) and Description fields to suite your purposes and upload your own bootstrapper ZIP file in place of the sample Grails_Bootstrapper_Debug.zip file.