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 mediation configuration in repository/conf/synapse-config directory.
• Place any additional files such as WSDL files, endpoint definitions, etc. referenced by your configuration 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 mediation to the libdirectory. 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 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:

• Add your mediation configuration to repository/conf/synapse-config directory.
• 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 mediation configuration into the repository directory.

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.