This article explains the various approaches that can be taken to deploy an Apache Synapse server instance. It provides information on each deployment option along with their software requirements and steps that need to be carried out.
Synapse requires Java 1.6 or higher and has been tested on Java runtime environments from Sun, IBM and Apple.Synapse is used on various operation systems, including Linux, Mac OS X, Solaris, Windows and AIX, as well as mainframe environments. The recommended operation system for production use is Linux since it offers a wider range of options to tune the TCP/IP stack. This is important to optimize the performance of the NIO HTTP transport.
When selecting the environment for deployment, the following known issues should be taken into account:
Synapse can be deployed in two different ways:
Since Synapse doesn't rely on any container API, the features offered are the same in both deployment scenarios, with very few exceptions:
In some scenarios Synapse is used to proxy services that are deployed themselves on an application server. In these cases it would be interesting to deploy Synapse on the same application server and use an in-VM transport instead of HTTP to communicate with these services. Note that for the moment no production-grade implementation of this type of transport exists yet for Axis2, but this might change in the future.
Since the features offered are almost the same, the differences between the two deployment options are mainly related to packaging and operational considerations:
The easiest way to get started with a stand-alone deployment is using the standard binary distribution ZIP or tarball (see download.html). It already contains everything that is needed to run Synapse stand-alone and you only need to customize it according to your requirements:
Since the standard binary distribution also contains samples and documentation, you might want to remove the following folders:
The bin directory contains Unix and Windows scripts to run Synapse:
Building a custom Synapse package based on the standard binary distribution is a manual process and this has some drawbacks:
Note that these problems not only arise in the development and maintenance phases of a project, but also when doing proof of concepts that you want to keep in a safe place for later reuse. One approach to overcome these difficulties is to use Maven to assemble a custom package. When used correctly, this approach solves all of the issues identified above. In particular Maven's dependency management together with the excellent assembly plugin can be used to automatically select the relevant JARs to include and pull them from Maven repositories. The remaining artifacts required to assemble the package can then be easily stored in a source control repository.
Synapse provides a Maven archetype that allows to set up this kind of project in only a few simple steps. To begin with, change to the directory where you want to create the project and issue the following command:
In case of problems, you can try to use the latest version of the archetype catalog:
Finally, if you have build Synapse from sources, you don't need to specify a catalog at all: the archetype is added automatically to the local catalog during the build.
In any case, when prompted by Maven, select synapse-package-archetype for the Synapse version you want to use. In the next step enter the values for groupId, artifactId and version for your project. You will also be prompted for a package name. Since the archetype doesn't contain any source code, this value is irrelevant and you can continue with the default value.
At this stage a Maven project has been created in a sub-directory with the same name as the artifactId specified previously. You should now customize this projects according to your needs:
The project is built as usual with the following command:
This will create a ZIP file (in the target directory) containing everything that is needed to run your custom Synapse configuration. You only need to extract it and use the appropriate script in the bin directory to start Synapse.
Synapse provides a standard WAR file that can be used to deploy mediation on a servlet container or on a J2EE application server. Note that this WAR file is not part of the downloadable distributions. It can be retrieved from the following location:
Customization of the Web application is similar to the stand-alone option, but the default directory structure is different: