src/site/apt/deployment.apt - synapse - Git at Google

 {Contents}

 %{toc}

 {Platform requirements}

   Synapse requires Java 1.5 or higher and has been tested on Java runtime environments from Sun,
   IBM and Apple. Note that the recommended Java version is 1.5 and that there is at least one
   known issue on Java 1.6 (see below). 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:

   * There is a known issue related to the script mediator when used with Java 1.6 on Windows.
     It has been observed that with this combination, random failures can occur during startup of
     Synapse. It is suspected that this issue is caused by a bug in BSF, but there is no solution
     or workaround yet.

   * The <<<synapse.bat>>> and <<<synapse.sh>>> scripts included in the binary distribution use
     the <<<-server>>> option which is not supported by IBM's JRE. This problem can be easily
     solved by manually editing these scripts to remove the unsupported <<<-server>>> option.
     See {{{https://issues.apache.org/jira/browse/SYNAPSE-454}SYNAPSE-454}}.

   * In the past several issues related to subtle concurrency problems have been reported with
     the non-blocking HTTP transport (which is the recommended HTTP implementation for Synapse)
     when used on more "exotic" platforms. While this has been improved it is recommended to
     thoroughly test the HTTP transport before deploying Synapse in a production environment based
     on these platforms. Please don't hesitate to report any issues using JIRA or by posting a
     message on the mailing list.

 {Overview of available deployment options}

   Synapse can be deployed in two different ways:

   * Stand-alone, i.e. as an independently managed Java process.

   * As a J2EE application (WAR) deployed into a simple servlet container (e.g. Tomcat) or a
     full-featured J2EE application server.

   []

   Since Synapse doesn't rely on any container API, the features offered are the same in both
   deployment scenarios, with very few exceptions:

   * There is a minor issue that prevents classpath resources from being used in a WAR deployment.
     See {{{https://issues.apache.org/jira/browse/SYNAPSE-207}SYNAPSE-207}}.

   * When deployed as a WAR file, Synapse can be configured with the standard Axis2 servlet based
     HTTP transport: while the recommended HTTP implementation for Synapse is the NIO HTTP
     transport, there might be situations where it is preferable or mandatory to use the HTTP
     protocol implementation of the application server.

   []

   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:

   * Many IT departments prefer deploying J2EE applications than managing stand-alone Java
     processes, because this allows them to leverage the management and monitoring facilities
     offered by the application server.

   * If the use case relies on JNDI resources such as JMS connection factories, JDBC data source
     and transactions it might be easier to set up and configure these resources when Synapse is
     deployed directly on the application server that hosts these resources.

 {Stand-alone deployment}

 * {Using the standard binary distribution}

   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:

   * Place your mediations in <<<repository/conf/synapse.xml>>>.

   * Place any additional files such as WSDL files, endpoint definitions, etc. referenced by your
     mediations in the <<<repository>>> directory.

   * Customize <<<repository/conf/axis2.xml>>> to enable and disable transports according to your needs.

   * Add any additional libraries required by your mediations to the <<<lib>>> directory. Alternatively
     modify <<<repository/conf/wrapper.conf>>> to add directories and JAR files to the classpath.

   * Add any required modules to <<<repository/modules>>>.

   * If necessary, modify <<<lib/log4j.properties>>> to configure logging.

   []

   Since the standard binary distribution also contains samples and documentation, you might want
   to remove the following folders:

   * <<<docs>>>

   * <<<repository/conf/sample>>>

   * <<<samples>>>

   []

   The <<<bin>>> directory contains Unix and Windows scripts to run Synapse:

   * <<<synapse.sh>>> and <<<synapse.bat>>> allow to run Synapse in non daemon mode.

   * <<<synapse-daemon.sh>>> is a Sys V init script that can be used on Unix systems to start and
     stop Synapse in daemon mode.

   * <<<install-synapse-service.bat>>> and <<<uninstall-synapse-service.bat>>> can be used on
     Windows to install Synapse as an NT service.

 * {Using Maven to build a custom distribution}

   Building a custom Synapse package based on the standard binary distribution is a manual process
   and this has some drawbacks:

   * The JAR files required to run Synapse must be selected manually and it is not easy to identify
     unused JARs that could be safely removed.

   * The process is not suitable if there is a requirement for strict configuration management.
     In particular:

     * Because of the large number of JAR files, managing the artifacts using a source control
       repository is not practical.

     * The process is not repeatable and there is no way to go back to a previous version of
       the artifacts.

   * When upgrading to a newer version of Synapse (or when working with snapshot versions), it
     is necessary either to manually replace the JARs in the current package or to start again
     from a new version of the standard binary distribution.

   * If Synapse needs to be deployed with slightly different configurations in multiple
     environments (e.g. test and production), the corresponding packages need to be prepared
     manually.

   []

   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
   {{{http://maven.apache.org/plugins/maven-assembly-plugin/}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:

 -------------------------------------------------------------------
 mvn archetype:generate -DarchetypeCatalog=http://synapse.apache.org
 -------------------------------------------------------------------

   In case of problems, you can try to use the latest version of the archetype catalog:

 -------------------------------------------------------------------
 mvn archetype:generate -DarchetypeCatalog=http://svn.apache.org/repos/asf/synapse/trunk/java/src/site/resources
 -------------------------------------------------------------------

   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 subdirectory with the same name as the
   <<<artifactId>>> specified previously. You should now customize this projects according to your needs:

   * Add your mediations to <<<repository/conf/synapse.xml>>>.

   * Customize the dependencies in <<<pom.xml>>>. In particular if additional transports such as
     JMS are needed, add the required dependencies here. Additional Axis2 modules should also be added here.

   * Enable and configure additional transports in <<<repository/conf/axis2.xml>>>.

   * Place any other files referenced by <<<synapse.xml>>> into the <<<repository>>> directory.

   []

   The project is built as usually with the following command:

 -----------
 mvn package
 -----------

   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 uncompress it and use the appropriate
   script in the <<<bin>>> directory to start Synapse.

 {WAR deployment}

   Synapse provides a standard WAR file that can be used to deploy mediations 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:

   * {{http://repo1.maven.org/maven2/org/apache/synapse/synapse-war/}} for released versions.

   * {{http://hudson.zones.apache.org/hudson/job/Synapse%20-%20Trunk/org.apache.synapse$synapse-war/}}
     for snapshot versions.

   []

   Customization of the Web application is similar to the stand-alone option, but the default
   directory structure is different:

   * <<<synapse.xml>>> and <<<axis2.xml>>> are placed into the <<<WEB-INF/conf>>> directory. All
     other files referenced by your mediations should go to the <<<WEB-INF/repository>>> directory.

   * Additional libraries must be placed into the standard <<<WEB-INF/lib>>> directory.

   * Axis2 modules are located in <<<repository/modules>>>.

   * <<<log4j.properties>>> is located in <<<WEB-INF/classes>>>.
	{Contents}

	%{toc}

	{Platform requirements}

	Synapse requires Java 1.5 or higher and has been tested on Java runtime environments from Sun,
	IBM and Apple. Note that the recommended Java version is 1.5 and that there is at least one
	known issue on Java 1.6 (see below). 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:

	* There is a known issue related to the script mediator when used with Java 1.6 on Windows.
	It has been observed that with this combination, random failures can occur during startup of
	Synapse. It is suspected that this issue is caused by a bug in BSF, but there is no solution
	or workaround yet.

	* The <<<synapse.bat>>> and <<<synapse.sh>>> scripts included in the binary distribution use
	the <<<-server>>> option which is not supported by IBM's JRE. This problem can be easily
	solved by manually editing these scripts to remove the unsupported <<<-server>>> option.
	See {{{https://issues.apache.org/jira/browse/SYNAPSE-454}SYNAPSE-454}}.

	* In the past several issues related to subtle concurrency problems have been reported with
	the non-blocking HTTP transport (which is the recommended HTTP implementation for Synapse)
	when used on more "exotic" platforms. While this has been improved it is recommended to
	thoroughly test the HTTP transport before deploying Synapse in a production environment based
	on these platforms. Please don't hesitate to report any issues using JIRA or by posting a
	message on the mailing list.

	{Overview of available deployment options}

	Synapse can be deployed in two different ways:

	* Stand-alone, i.e. as an independently managed Java process.

	* As a J2EE application (WAR) deployed into a simple servlet container (e.g. Tomcat) or a
	full-featured J2EE application server.

	[]

	Since Synapse doesn't rely on any container API, the features offered are the same in both
	deployment scenarios, with very few exceptions:

	* There is a minor issue that prevents classpath resources from being used in a WAR deployment.
	See {{{https://issues.apache.org/jira/browse/SYNAPSE-207}SYNAPSE-207}}.

	* When deployed as a WAR file, Synapse can be configured with the standard Axis2 servlet based
	HTTP transport: while the recommended HTTP implementation for Synapse is the NIO HTTP
	transport, there might be situations where it is preferable or mandatory to use the HTTP
	protocol implementation of the application server.

	[]

	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:

	* Many IT departments prefer deploying J2EE applications than managing stand-alone Java
	processes, because this allows them to leverage the management and monitoring facilities
	offered by the application server.

	* If the use case relies on JNDI resources such as JMS connection factories, JDBC data source
	and transactions it might be easier to set up and configure these resources when Synapse is
	deployed directly on the application server that hosts these resources.

	{Stand-alone deployment}

	* {Using the standard binary distribution}

	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:

	* Place your mediations in <<<repository/conf/synapse.xml>>>.

	* Place any additional files such as WSDL files, endpoint definitions, etc. referenced by your
	mediations in the <<<repository>>> directory.

	* Customize <<<repository/conf/axis2.xml>>> to enable and disable transports according to your needs.

	* Add any additional libraries required by your mediations to the <<<lib>>> directory. Alternatively
	modify <<<repository/conf/wrapper.conf>>> to add directories and JAR files to the classpath.

	* Add any required modules to <<<repository/modules>>>.

	* If necessary, modify <<<lib/log4j.properties>>> to configure logging.

	[]

	Since the standard binary distribution also contains samples and documentation, you might want
	to remove the following folders:

	* <<<docs>>>

	* <<<repository/conf/sample>>>

	* <<<samples>>>

	[]

	The <<<bin>>> directory contains Unix and Windows scripts to run Synapse:

	* <<<synapse.sh>>> and <<<synapse.bat>>> allow to run Synapse in non daemon mode.

	* <<<synapse-daemon.sh>>> is a Sys V init script that can be used on Unix systems to start and
	stop Synapse in daemon mode.

	* <<<install-synapse-service.bat>>> and <<<uninstall-synapse-service.bat>>> can be used on
	Windows to install Synapse as an NT service.

	* {Using Maven to build a custom distribution}

	Building a custom Synapse package based on the standard binary distribution is a manual process
	and this has some drawbacks:

	* The JAR files required to run Synapse must be selected manually and it is not easy to identify
	unused JARs that could be safely removed.

	* The process is not suitable if there is a requirement for strict configuration management.
	In particular:

	* Because of the large number of JAR files, managing the artifacts using a source control
	repository is not practical.

	* The process is not repeatable and there is no way to go back to a previous version of
	the artifacts.

	* When upgrading to a newer version of Synapse (or when working with snapshot versions), it
	is necessary either to manually replace the JARs in the current package or to start again
	from a new version of the standard binary distribution.

	* If Synapse needs to be deployed with slightly different configurations in multiple
	environments (e.g. test and production), the corresponding packages need to be prepared
	manually.

	[]

	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
	{{{http://maven.apache.org/plugins/maven-assembly-plugin/}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:

	-------------------------------------------------------------------
	mvn archetype:generate -DarchetypeCatalog=http://synapse.apache.org
	-------------------------------------------------------------------

	In case of problems, you can try to use the latest version of the archetype catalog:

	-------------------------------------------------------------------
	mvn archetype:generate -DarchetypeCatalog=http://svn.apache.org/repos/asf/synapse/trunk/java/src/site/resources
	-------------------------------------------------------------------

	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 subdirectory with the same name as the
	<<<artifactId>>> specified previously. You should now customize this projects according to your needs:

	* Add your mediations to <<<repository/conf/synapse.xml>>>.

	* Customize the dependencies in <<<pom.xml>>>. In particular if additional transports such as
	JMS are needed, add the required dependencies here. Additional Axis2 modules should also be added here.

	* Enable and configure additional transports in <<<repository/conf/axis2.xml>>>.

	* Place any other files referenced by <<<synapse.xml>>> into the <<<repository>>> directory.

	[]

	The project is built as usually with the following command:

	-----------
	mvn package
	-----------

	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 uncompress it and use the appropriate
	script in the <<<bin>>> directory to start Synapse.

	{WAR deployment}

	Synapse provides a standard WAR file that can be used to deploy mediations 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:

	* {{http://repo1.maven.org/maven2/org/apache/synapse/synapse-war/}} for released versions.

	* {{http://hudson.zones.apache.org/hudson/job/Synapse%20-%20Trunk/org.apache.synapse$synapse-war/}}
	for snapshot versions.

	[]

	Customization of the Web application is similar to the stand-alone option, but the default
	directory structure is different:

	* <<<synapse.xml>>> and <<<axis2.xml>>> are placed into the <<<WEB-INF/conf>>> directory. All
	other files referenced by your mediations should go to the <<<WEB-INF/repository>>> directory.

	* Additional libraries must be placed into the standard <<<WEB-INF/lib>>> directory.

	* Axis2 modules are located in <<<repository/modules>>>.

	* <<<log4j.properties>>> is located in <<<WEB-INF/classes>>>.