Skip to end of metadata
Go to start of metadata

The following sub-sections help you to get an in-depth understanding of how to manage WSO2 products on Mesos DC/OS.

You need a basic understanding of Docker, Mesos DC/OS and Puppet to work on this tutorial.

Deploying a WSO2 product on Mesos DC/OS

Follow the instructions below to deploy a new WSO2 product on Mesos DC/OS:

Step 1 - Build the product Docker image

To manage configurations and artifacts when building Docker images, it is recommended to use WSO2 Puppet Modules as the provisioning method. A specific data set for Mesos DC/OS platform is available in WSO2 Puppet Modules. It is possible to use this data set to build Dockerfiles for WSO2 products targeting Mesos DC/OS with minimum configuration changes. Carry out the following steps to build the Docker image for the relevant WSO2 product.

Step 1.1 - Download the Puppet Modules
  1. Download WSO2 Puppet module 2.1.0 distribution from the GitHub repository.
  2. Unzip the distribution to a place of your choice. This location is referred to as <PUPPET_HOME> hereafter.

  3. Set the environment variable PUPPET_HOME pointing to the Puppet artifact location.

    export PUPPET_HOME=~/temp/puppet
Step 1.2 - Copy the required artifacts into Puppet
  1. Download the relevant WSO2 product distribution and copy it into the <PUPPET_HOME>/modules/<PRODUCT_NAME>/files directory.

  2. Download the JDK 1.7_80 distribution and copy it into the <PUPPET_HOME>/modules/wso2base/files directory.

  3. Copy the MySQL Connector JAR 5.1.36 file to the <PUPPET_HOME>/modules/<PRODUCT_NAME>/files/configs/repository/components/lib directory.
  4. Copy the mesos-membership-scheme-1.0.0.jar  and Kernel patches if needed as in the Mesos DC/OS membership scheme, which explains the clustering support aspect for WSO2 products on Mesos DC/OS.

    If you change the versions of any artifacts mentioned under step 1.2 above, you also need to change the references to those versions/file names in the Puppet configuration.

Step 1.3 - Build the WSO2 product Docker image(s)
  1. Download WSO2 Dockerfiles 1.2.0 distribution from the GitHub repository.
  2. Unzip the distribution to a place of your choice. Let's refer to this location as <DOCKERFILES_HOME> hereafter.
  3. Navigate to the relevant product directory location, which is <DOCKERFILES_HOME> /<PRODUCT_NAME>. This contains a Dockerfile and some helper scripts to build the Docker image.
  4. Use the build script to build the Docker image.

    build.sh usage
    Usage: ./build.sh -v [product-version]
      -v	[REQUIRED] Product version of <product_name>
      -l	[OPTIONAL] '|' separated <product_name> profiles to build. "default" is selected if no value is specified.
      -i	[OPTIONAL] Docker image version.
      -e	[OPTIONAL] Product environment. If not specified this is defaulted to "dev".
      -o	[OPTIONAL] Preferred organization name. If not specified, will be kept empty.
      -q	[OPTIONAL] Quiet flag. If used, the docker build run output will be suppressed.
      -r	[OPTIONAL] Provisioning method. If not specified this is defaulted to "default". Available provisioning methods are default, puppet.
      -t	[OPTIONAL] Image name. If this is specified, it will be used as the image name instead of "wso2/{product/}" format.
      -y	[OPTIONAL] Automatic yes to prompts; assume "y" (yes) as answer to all prompts and run non-interactively.
      -s	[OPTIONAL] Platform to be used to run the Dockerfile (ex.: mesos). If not specified will assume the value as 'default'.
  5. Use the following command to build the product image with standalone configurations, using Puppet configurations, targeting Mesos DC/OS. This build script uses the PUPPET_HOME environment variable to find the Puppet Modules, as explained in Step 1.1.

    ./build.sh -v [product-version] -s mesos -r puppet

    It is possible to use the same Puppet configurations to build different profiles that are supported by the product, by using the -l flag.
    For example, use the following command to build the api-store profile for WSO2 API Manager.

    /build.sh -v [product-version] -s mesos -r puppet -l api-store
  6. Verify if the built Docker image exists, with the correct image name and tag, by executing the following command in the local Docker build machine.

    The following message appears after the build process is complete. List the Docker images by issuing the following command only after the build process is finished.

    Build process completed in x minutes and yy seconds
    docker images
    Output of 'docker images' command:
    REPOSITORY                               TAG                   IMAGE ID            CREATED             VIRTUAL SIZE
    wso2/<product_name>-<version>            1.0.0                 c8ab0b692142        19 hours ago        1.45 GB

Step 2 - Setup Mesos DC/OS and WSO2 Mesos Artifacts

Step 2.1 - Download WSO2 Mesos Artifacts
  1. Download WSO2 Mesos Artifacts 1.0.0 from the GitHub repository release page. 
  2. Unzip the distribution to a place of your choice. Let's refer to this location as <MESOS_HOME> hereafter.
Step 2.2 - Start the Mesos DC/OS cluster

Setup Mesos DC/OS as follows as this approach uses DC/OS boxes for the Master and Node Virtual Machines (VMs), and also because it is very easy to destroy and recreate a cluster. 

Refer to the Mesos DC/OS documentation to learn more about the various options available to setup Mesos DC/OS.

  1. Clone the Mesos Vagrant setup Git repository.

    git clone https://github.com/dcos/dcos-vagrant.git
  2. Set up a Mesos DC/OS Cluster.
    For more information, go to https://github.com/dcos/dcos-vagrant/blob/master/docs/deploy.md.

Step 2.3 - Load the Docker images to Nodes/Docker registry

Copy the required Docker images over to the Mesos DC/OS Agent Nodes using one of the following options:

  • Manual approach
    1. Create a tarball of the required image using the docker save command. 

      docker save <IMAGE_ID> > /tmp/<IMAGE_ID>.tar
    2. SCP the tarball to each node.

    3. Reload the images from the copied tarballs on the nodes using the docker load command.

      ssh <MESOS_AGENT_NODE_USERNAME>@<MESOS_AGENT_NODE_IP> "docker load < <IMAGE_ID>.tar"

      Alternatively, if you are using a private Docker registry, transfer the images to that registry.

  • Helper script approach
    Execute the  load-images.sh helper script to seamlessly transfer images to the Mesos DC/OS nodes.
    When this script is executed, the steps mentioned in the manual approach are automatically executed. Furthermore, when the helper script is executed, it searches for any Docker images with mesos as a part of its name on your local machine and asks for verification to transfer them to the Mesos DC/OS nodes. Make sure that the Mesos DC/OS command line client dcos-cli is functioning on your local machine in order for the script to retrieve the list of Mesos DC/OS nodes. You can optionally provide a search pattern if you want to override the default mesos string.
load-images.sh usage
Usage: ./load-images.sh [OPTIONS]
Transfer Docker images to Mesos Nodes
  -u	[OPTIONAL] Username to be used to connect to Mesos Nodes. If not provided, default "centos" is used.
  -p	[OPTIONAL] Optional search pattern to search for Docker images. If not provided, default "mesos" is used.
  -k	[OPTIONAL] Optional key file location. If not provided, key file will not be used.
  -h	[OPTIONAL] Show help text.
Ex: ./load-images.sh
Ex: ./load-images.sh -u centos -p wso2is -k /home/ssh_key.pem
Step 2.4 - Deploy the WSO2 product on Mesos DC/OS
  1. Navigate to the relevant product directory location, which is <MESOS_HOME>/<PRODUCT_NAME>. This contains definitions (YAML files) for Marathon applications and some helper scripts.
  2. Deploy the artifacts using the deploy script.


    It is possible to start a distributed deployment of a product using the same deploy script, by building and loading the distributed deployment related Docker images for the relevant profiles of the product into the Mesos DC/OS nodes.

    ./deploy.sh -d

    After the artifacts are successfully deployed, the following message is displayed.

    Successfully deployed <PRODUCT>-<PROFILE_NAME>

Step 3 - Access the management console

  1. Add a host entry in the  /etc/hosts file (for Linux) to map the hostname to the Mesos DC/OS node IP. 
    For example, if the Mesos DC/OS node IP is, the /etc/hosts entry is as follows:
    This node should be the Mesos agent node that runs the Marathon-lb Docker container.

    /etc/hosts	marathon-lb.marathon.mesos
  2. Access the respective WSO2 product management console URL:


You can obtain the WSO2 product management console URL from product startup logs.

Undeploying a WSO2 product on Mesos DC/OS

Follow the instructions below to undeploy WSO2 products on Mesos DC/OS:

  1. Navigate to relevant product directory on Mesos DC/OS repository in the <MESOS_HOME>/<PRODUCT_NAME> directory.
  2. Use the undeploy script to terminate the product specific DB nodes, undeploy Marathon applications.


    If the -f flag is provided when running the undeploy.sh script, it also undeploys the shared Governance and User DB nodes, Marathon application.

    ./undeploy.sh -f
  • No labels