Implementing an Effective Deployment Process for WSO2 Middleware

WSO2 provides middleware solutions for Integration, API Management, Identity Management, IoT and Analytics. Running these products on a local machine is quite straightforward; it would just need to install Java, download the required WSO2 distribution, extract the zip file and run the executable. This would provide a middleware testbed for the user in no time. If the solution needs multiple WSO2 products those can be run on the same machine by changing the port-offsets and configuring the integrations accordingly. This works very well for trying out product features and implementing quick PoCs. However, once the preliminary implementation of the project is done, a proper deployment process would be needed for moving the system to production. Otherwise, project maintenance might get complicated over time.

Any software project would need at least three environments for managing development, testing and the live deployments. More importantly a software governance model would be needed for delivering new features, improvement, bug fixes and managing the overall development process. This becomes crucial when the project has to implement the system on top of a middleware solution. A software delivery would need to include both middleware and application changes. Those might have considerable amount of prerequisites, artifacts and configurations. Without having a well defined process, it would be difficult to manage a such project efficiently.

Things to Consider

On high level the following points would need to be considered when implementing an effective deployment process:

  • Infrastructure

WSO2 middleware can be deployed on physical machines, virtual machines and on containers. Up to now most deployments have been done on virtual machines. In around year 2015, WSO2 users started moving towards container based deployments using Docker, Kubernetes and Mesos DC/OS. This approach optimizes the overall infrastructure usage compared to VMs. As containers do not need a dedicated operating system instance, it needs less resources for running an application in contrast to a VM. In addition, the container ecosystem makes the deployment process much easier using light weight container images and container image registries. WSO2 provides Puppet Modules, Dockerfiles, Docker Compose, Kubernetes and Mesos (DC/OS) artifacts for automating such deployments.

  • Configuration Management

In each WSO2 product configurations can be found inside repository/conf folder. This folder contains a collection of configuration files corresponding to the features that the product provides. The simplest solution is to maintain these files in a version control system (VCS) such as Git. If the deployment has multiple environments and a collection of products it might be better to consider using a configuration management system such as Ansible, Puppet, Chef or Salt Stack for reducing the configuration value duplication. WSO2 ships Puppet modules for all WSO2 products for this purpose.

  • Extension Management

WSO2 middleware provides extension points in all WSO2 products for plugging in required features. For an example in WSO2 Identity Server a custom user store manager can be implemented for connecting to an external user stores which communicates via a proprietary protocol. In ESB API handlers or class mediators can be implemented for executing custom mediation logic. Almost all of these extensions are written in Java and deployed as JAR files. These files need to be copied to repository/components/lib folder or repository/components/dropins folder if they are OSGi compliant.

  • Deployable Artifact Management

Artifacts that can be deployed in repository/deployment/server folder are considered as deployable artifacts. For an example in ESB, proxy services, REST APIs, inbound endpoints, sequences, security policies, can be deployed in runtime via the above folder. These artifacts are recommended to be created in WSO2 Developer Studio (DevStudio) and packaged into Carbon Archive (CAR) files for deploying them as collections. WSO2 DevStudio provides a collection of project templates for managing deployable files of all WSO2 products. These files can be effectively maintained using a VCS.

  • Applying Patches/Updates

Patches are applied to a WSO2 product by copying the patch<number> folder which is found inside the patch zip file to the repository/deployment/patches/ folder. Fixes for any Jaggery UI components will need to be copied to repository/deployment/server/jaggeryapps/ as described in the patch README.txt file. WSO2 recently introduced a new way of applying patches for WSO2 products with WSO2 Update Manager (WUM). The main difference of updates in contrast to the the previous patch model is that, with updates fixes/improvements cannot be applied selectively. It applies all the fixes issued up to a given point using a CLI. This is the main intension of this approach. More information on WUM can be found here. The list of products supported via WUM can be found here.

  • Lifecycle Management

In any software project it is important to have at least three environments for managing development, testing and production deployments separately. New features, bug fixes or improvements need to be first done in the development environment and then moved to the testing environment for verification. Once the functionality and performance are verified the changes can be applied in production as explained in the “Rolling Out Changes” section.

Changes can be moved from one environment to the other as a delivery. A delivery need to contain a completed set of changes. Deliveries can be numbered and managed via tags in Git. The key advantage of using this approach is the ability to track, apply and rollback updates at any given time. The performance verification step might need to have resources identical to the production environment for executing load tests. This is vital for deployments where performance is critical.

  • Rolling Out Changes

Changes to the existing solution can be rolled out in two main methods:

1. Incremental Deployment

This is also known as Canary Release. The idea of this approach is to incrementally apply changes to the existing solution without having to completely switch the entire deployment to the new solution version. This gives the ability to verify the delivery in the production environment using a small portion of the users before propagating it to everyone.

2. Blue-Green Deployment

In Blue-Green deployment method, the deployment is switched to the newer version of the solution at once. It would need an identical set of resources for running the newer version of the solution in parallel to the existing deployment until the newer version is verified. In case of a failure, the system can be switched back to the previous version via the router. Taking such approach might need thorough testing procedure compared to the first approach.

Deployment Process Approach 1

Figure 1: Deployment Process Approach 1

The above diagram illustrates the simplest form of executing a WSO2 deployment effectively. In this model the configuration files, deployable artifacts and extension source code are maintained in a version control system. WSO2 product distributions are maintained separately in a file server. Patches/updates are directly applied to the product distributions and new distributions are created. The separation of distributions and artifacts allows product distributions to be updated without loosing any project content. As shown by the green color box at the middle, combining latest product distributions, configuration files, deployable artifacts and extensions, deployable product distributions are created. Deployable distributions can be extracted on physical, virtual machines or containers and run. Depending on the selected deployment pattern, multiple deployable distributions will need to be created for a product.

In a containerized deployment each deployable product distribution will have a container image. In addition according to the containerized platform a set of orchestration and load balancing artifacts might be used.

Deployment Process Approach 2

Figure 2: The Deployment Process Approach 2

In the second approach, a configuration management system has been used for reducing the duplication of the configuration data and automating the installation process. Similar to the approach one deployable artifacts, configuration data and extension source code are managed in a version control system. Configuration data needs be stored in a format that is supported by the configuration management system. For an example, in Puppet configuration data are either stored in manifest files or Hiera YAML files. In this approach deployable WSO2 product distributions are not created, rather that process is executed by the configuration management system inside a physical machine, virtual machine or in a container at the container build time.


WSO2 middleware are shipped as a collection of product distributions. Those can be run on a local machine in minutes. A middleware solution might use a collection of WSO2 products for implementing an enterprise system. Each WSO2 product will have a set of configurations, deployable artifacts and optionally extensions for a given solution. These can be managed effectively in software projects in two approaches.

Any of the above deployment approaches can be followed with any infrastructure. If a configuration management system is used, it can be used for installing and configuring the solution on virtual machines and as well as on containers. The main difference with containers is that configuration management agent will only be triggered at the container image build time. It may not be run in the when the container is running.