WSO2 Ant Application Deployer

Note :  You would be able to achieve most the requirements described here using puppet scripts, which would be the ideal way of doing it. Anyway, if you are still interested, you can continue reading.

Ant application deployer is a custom deployer written to deploy an Ant script in a WSO2 Carbon based server, which will then get executed automatically. Using Ant deployer, you can deploy any artifact/jar/configuration into a carbon server using a single file.

Along with the Ant deployer, following custom tasks are also included.

1. server
• This can be used to shutdown/restart a local/remote Carbon Server
2. registry
• This can be used to insert metadata into a local/remote registry of a WSO2 server

Note : Ant application deployer should be used if and only if, Ant applications are deployed by trusted parties. Also, this shouldn't be used in a cloud environment.

Why Ant application deployer

Lets assume you have a requirement to configure an WSO2 ESB server as below.

1. Install a set of custom mediators
2. Deploy a set of carbon applications with sequences/registry resources which uses those custom mediators
3. Deploy APIs and templates which cannot be included in car file at the moment
4. Add metadata like properties, associations along with the registry resources.

Notes :  Support for APIs and templates would be added in the future, but at the moment it is not supported.

If you want to do above configurations, then you might need to follow below steps.

1. Copy jar files
2. Restart the server
3. Copy carbon applications
4. Copy APIs and templates
5. Manually add metadata

But, using Ant deployer with its custom tasks mentioned above, you can create a single deployable artifact which does everything mentioned above using ant. Only step that you will need to do is, just to copy the all in one zip file into the relevant location. Then the Ant script in the zip file will be automatically executed and above steps would be executed.

Although above is a simple usecase, you would be able to do more cool stuff such as to configure/patch/migrate a whole carbon installation with a proper ant script.

 

Installation

1. Copy the jar named org.wso2.carbon.extensions.antdeployer-1.0.0.jar into repository/components/dropins directory of the carbon 4.0.x based server.
2. Restart the server

Using Ant Deployer

 

Properties

Following properties can be used within the Ant script to get the information about the server being runing.

Property	Example Value
carbon.home	/home/ruchira/wso2esb-4.5.0
carbon.conf	/home/ruchira/wso2esb-4.5.0/repository/conf
carbon.logs	/home/ruchira/wso2esb-4.5.0/repository/logs
carbon.dropins	/home/ruchira/wso2esb-4.5.0/repository/components/dropins
carbon.lib	/home/ruchira/wso2esb-4.5.0/repository/components/libs
carbon.repo	/home/ruchira/wso2esb-4.5.0/repository/deployment/server/
carbon.tenants	/home/ruchira/wso2esb-4.5.0/repository/tenants
carbon.components	/home/ruchira/wso2esb-4.5.0/repository/components/plugins
carbon.tmp	/home/ruchira/wso2esb-4.5.0/tmp
carbon.catalina	/home/ruchira/wso2esb-4.5.0/lib/tomcat/work/Catalina

Custom Ant Tasks

server

This Ant task can be used to restart/shutdown a local/remote carbon server.

<server
        url="https://serverhost:port/services"
        username="user"
        password="pass"
        action="restart|shutdown|gracerestart|graceshutdown"
        target="t1"/>

For the action, you need to specify one of the followings

1. shutdown
• Discard any requests currently being processed and immediately shutdown the server.
2. restart
• Discard any requests currently being processed and immediately restart the server.
3. graceshutdown
• Stop accepting new requests, continue to process already received requests, and then shutdown the server.
4. gracerestart
• Stop accepting new requests, continue to process already received requests, and then restart the server.

Shutdown/restart different server

<server
        url="https://serverhost:port/services"
        username="user"
        password="pass"
        action="restart|shutdown|gracerestart|graceshutdown"/>

Shutdown/restart same server

<server target="t1" action="restart|shutdown|gracerestart|graceshutdown"/>

When the same server is being restarted/shutdown, then everything that you need to execute after restart/shutdown, should be defined as a separate task/tasks and specify first task with "target" attribute.

If the server is just shutdown, then "target" attribute can be omitted.  But if you have specified a “target” attribute even for shutdown action, then that target will be executed whenever the server is being restarted.

registry

Registry metadata can be added by specifying  the paths to metadata files as below.

<registry password="pass" url="https://serverhost:port/registry" username="user">
    <metadata path="registry-meta/meta1.xml"/>
    <metadata path="registry-meta/meta2.xml"/>
</registry>

Further, if the metadata is added to the resources which are being deployed by the *.car files in the same Ant application, then there is a possibility of executing metadata task before the resources get added to the registry.

As a solution for this, registry Ant task waits and retries several times until resources get deployed.  Default value for wait is 10s and retry count is 5.

Anyway, these wait and retry times can be overridden by specifying following properties in the build.xml.

<property name="registry.retries" value="4"/>
<property name="registry.sleep" value="20000"/>

Using your own custom tasks

If any additional custom tasks are required depending on your environment, those jars can be added either into repository/components/dropins (OSGI bundles) or repository/components/lib (Non-OSGI jars).

Then, above custom tasks can be used in your ant scripts as below by defining the task class in every script.

<target name="use" description="Use the Task" depends="jar">
    <taskdef name="helloworld" classname="com.mycompany.HelloWorld"/>
    <helloworld/>
</target>

Adding task definitions in each script can be avoided by defining them in repository/conf/ant-deployer.xml as below.

<AntDeployer xmlns="http://wso2.org/carbon/antdeployer">
    <Tasks>
        <Task name="helloworld" classname="com.mycompany.HelloWorld"/>
        <Task name="hellouniverse" classname="com.mycompany.HelloUniverse"/>
    </Tasks>
</AntDeployer>

Then, tasks can be used directly without defining them in the scripts.

Metadata Configuration

Adding metadata

Following is an example metadata file. When there are multi-valued properties, “append” attribute need to be specified.

<metadata xmlns="http://wso2.org/carbon/registry/metadata">
    <resource path="/_system/config/resource1">
        <associations>
            <association path="/_system/governance/resource2"
                         type="depends"/>
            <association path="/_system/governance/resource3"
                         type="depends"/>
        </associations>
        <properties>
            <property name="p1" append=”true”>v1</property>
            <property name="p2">v2</property>
        </properties>
        <tags>
            <tag>t1</tag>
            <tag>t2</tag>
        </tags>
    </resource>
</metadata>

Removing resources/metadata from Registry

By defining an attribute named “remove” within each resource, association, property and tag elements,  you can instruct to remove those resources/metadata from the registry.

<metadata xmlns="http://wso2.org/carbon/registry/metadata">
    <resource path="/_system/config/resource1" remove="true"/>
    <resource path="/_system/config/resource2">
        <associations>
            <association path="/_system/governance/resource3"
                         type="depends" remove="true"/>
        </associations>
        <properties>
            <property name="p1" append=”true” remove="true">v1</property>
            <property name="p2" remove="true"/>
        </properties>
        <tags>
            <tag remove="true"/>
        </tags>
    </resource>
</metadata>

Trying it out

 

The source code, the pre-build jar and a sample Ant application written for WSO2 ESB server can be found at [1]. This sample Ant application will do the following steps.

1. Copying the mysql driver
2. Restarting the server
3. Deploying ESB sequence template named template1
4. Deploying ESB API named api1
5. Deploying the carbon application named sample-antapp_1.0.0.car which includes
• A proxy service named SampleProxy
• Registry resources named endpoint1.xml and endpoint2.xml which will be deployed at /_system/antapp-sample/endpoints
6. Creating a set of associations between /_system/antapp-sample and above endpoint1.xml, endpoint2.xml resources
7. Adding a set properties named p1, p2 etc. and tags named t1, t2 etc into the collection /_system/antapp-sample and endpoint1.xml, endpoint2.xml resources

In order to try it out,

1. Install the Ant deployer into WSO2 ESB 4.5.0 server following the above installation steps
• Pre-built jar can be found in lib directory at [1]
2. Create a directory at <cabon_home>/repository/deployment/server/antapps
• e.g. wso2esb-4.5.0/repository/deployment/server/antapps
3. Copy the sample-antapp.zip file into the antapps directory
• Pre-build antapp can be found in lib directory at [1]
4. Restarting logs should be able to notice either in the console or  server logs within a few seconds

Resources

[1] https://svn.wso2.org/repos/wso2/people/ruchira/ant-deployer
[2] build.xml in the sample antapp

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="sample-antapp" basedir="." default="t0">
    <target name="t0" description="Copy jars into Carbon Server and restart">
        <copy file="jars/mysql-connector-java-5.1.22-bin.jar"
              todir="${carbon.lib}"/>
        <server target="t1"/>
    </target>
    <target name="t1" description="Copy artifacts">
        <copy file="templates/template1.xml"
              todir="${carbon.repo}/synapse-configs/default/templates"/>
        <copy file="apis/api1.xml"
              todir="${carbon.repo}/synapse-configs/default/api"/>
        <copy file="carbonapps/sample-antapp_1.0.0.car"
              todir="${carbon.home}/repository/carbonapps/0"/>
        <registry url="https://localhost:9443/registry"
                  username="admin" password="admin">
            <metadata path="registry-meta/*"/>
        </registry>
    </target>
    <target name="t2" description="Create ruchira directory">
        <mkdir dir="${carbon.home}/ruchira"/>
    </target>
</project>

[3]  Registy metadata xml in the sample antapp

<metadata xmlns="http://wso2.org/carbon/registry/metadata">
    <resource path="/_system/antapp-sample">
        <associations>
            <association path="/_system/antapp-sample/endpoints/endpoint1.xml"
                         type="depends"/>
            <association path="/_system/antapp-sample/endpoints/endpoint2.xml"
                         type="depends"/>
        </associations>
        <properties>
            <property name="p1">v1</property>
            <property name="p2">v2</property>
        </properties>
        <tags>
            <tag>t1</tag>
            <tag>t2</tag>
        </tags>
    </resource>
    <resource path="/_system/antapp-sample/endpoints/endpoint1.xml">
        <associations>
            <association path="/_system/antapp-sample/endpoints/endpoint2.xml"
                         type="sibling"/>
        </associations>
        <properties>
            <property name="p1">e1v1</property>
            <property name="p2">e1v2</property>
        </properties>
        <tags>
            <tag>e1t1</tag>
            <tag>e1t2</tag>
        </tags>
    </resource>
    <resource path="/_system/antapp-sample/endpoints/endpoint2.xml">
        <associations>
            <association path="/_system/antapp-sample/endpoints/endpoint1.xml"
                         type="sibling"/>
        </associations>
        <properties>
            <property name="p1">e2v1</property>
            <property name="p2">e2v2</property>
        </properties>
        <tags>
            <tag>e2t1</tag>
            <tag>e2t2</tag>
        </tags>
    </resource>
</metadata>