WSO2 Micro Integrator on AWS User Guide

Overview

This image runs the WSO2 Micro Integrator, a lightweight, cloud native, configuration driven integration runtime from the WSO2 project. It implements enterprise integration patterns and lets you expose REST and SOAP APIs, proxy services, message mediation and routing as hot deployable integration artifacts. Only the Apache 2.0 licensed open source runtime is shipped, run on a headless OpenJDK 21 Java runtime.

The runtime is installed under /opt/wso2mi and runs as a dedicated unprivileged wso2 system account under a systemd service that starts it on boot and restarts it on failure. The distribution exposes two planes:

• Integration / data plane — the Synapse passthrough transport on HTTP port 8290 and HTTPS port 8253, bound to all interfaces so the APIs and proxy services you deploy receive traffic. A sample health check API is baked into the image so a GET to /health on port 8290 returns a 200 JSON body immediately after launch.
• Management API — HTTPS port 9164, used by the WSO2 MI command line tool. The runtime binds this to all interfaces with no configuration key to change that, so a scoped nftables loopback guard drops external traffic to the management ports (9164 and the internal API 9201) and an nginx reverse proxy on port 80 provides a controlled front. The management API is therefore never directly reachable off the instance.

The management API administrator password is generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share a password. It is written to /root/wso2mi-credentials.txt with mode 0600 so that only the root user can read it. The shipped image carries no working default credential — the WSO2 default admin/admin is rejected.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network, port 80 for the management front, and the data plane ports (8290, 8253) from the networks your integration clients use
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for WSO2 Micro Integrator. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger (the runtime is a JVM workload). Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network, port 80 for the management front, and the data plane ports (8290, 8253) your clients use. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes approximately one minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg WSO2 Micro Integrator Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, 8290 and 8253 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=wso2-micro-integrator}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

Step 4: Confirm the Runtime Is Healthy

The WSO2 Micro Integrator and its nginx management front start automatically on boot. Confirm both services are active:

systemctl is-active wso2mi.service nginx.service

Both report active. The runtime version and Java runtime:

basename $(readlink -f /opt/wso2mi); java -version

Step 5: Exercise the Integration Data Plane

A sample health check API is deployed on the Synapse passthrough transport. It answers without authentication and proves the data plane is routing requests:

curl -s http://127.0.0.1:8290/health

The response is {"status":"healthy","runtime":"wso2-micro-integrator","cloudimg":true}. From outside the instance the same API is reachable at http://<public-ip>:8290/health once your security group opens port 8290.

The data plane also listens for HTTPS on port 8253. Point your own API and proxy clients at the instance on 8290 (HTTP) or 8253 (HTTPS).

Step 6: Retrieve the Management API Password

The per instance management API administrator password is written to a root only file on first boot. Confirm the file exists with mode 0600:

sudo ls -l /root/wso2mi-credentials.txt

Read the full file (management username, password and the resolved URLs) when you need the password:

sudo cat /root/wso2mi-credentials.txt

Step 7: Sign In to the Management API

The management API is bound to loopback and fronted by nginx on port 80. From the instance, read the password into a shell variable and request an access token. The per instance password authenticates, while both the WSO2 default admin/admin and any wrong password are rejected with 401:

PW=$(sudo awk -F= '/ADMIN_PASSWORD/{print $2}' /root/wso2mi-credentials.txt)
curl -sk -o /dev/null -w 'per-instance login: HTTP %{http_code}\n' -u "admin:$PW" https://127.0.0.1:9164/management/login
curl -sk -o /dev/null -w 'default admin/admin: HTTP %{http_code}\n' -u admin:admin https://127.0.0.1:9164/management/login

You will see per-instance login: HTTP 200 and default admin/admin: HTTP 401. The nginx front exposes the same management API off the instance at http://<public-ip>/management/login (HTTP Basic auth). Terminate TLS at nginx or a load balancer before exposing it beyond a trusted network.

Step 8: Understand the Loopback Guard

The runtime binds the management API (9164) and internal API (9201) to all interfaces and offers no configuration key to restrict them to loopback. cloudimg installs a scoped nftables table that drops inbound non loopback traffic to those two ports, so the management plane is reachable only via loopback and the nginx front. Inspect the rule:

sudo nft list table inet cloudimg_wso2_guard

The table drops tcp dport { 9164, 9201 } for any non loopback source. The data plane (8290, 8253), SSH (22) and the management front (80) are untouched, and your own security group rules are not affected.

Step 9: Deploy Your Own Integration Artifacts

The WSO2 Micro Integrator hot deploys artifacts from its deployment directory. Copy a Composite Application archive (a .car file built with the WSO2 Integration tooling) or raw Synapse configurations into the server deployment tree and the runtime picks them up without a restart:

• Composite Application archives: /opt/wso2mi/repository/deployment/server/carbonapps/
• Raw Synapse APIs, proxy services and sequences: /opt/wso2mi/repository/deployment/server/synapse-configs/default/

Deployed REST APIs are served on the data plane transport (8290/8253) at the context you define, exactly like the baked sample /health API.

Security

• Secure first boot — a one shot service generates a unique management API administrator password per instance and writes it into the runtime configuration before the runtime starts. No shared or default credential ships in the image, and admin/admin is rejected.
• Loopback guarded management plane — the management and internal APIs are reachable only via loopback and the nginx front on port 80. Restrict that front, plus the data plane ports, to trusted networks with your security groups.
• Encryption — enable AWS EBS encryption on the root volume to protect configuration and artifacts at rest, and terminate TLS at nginx or a load balancer for encrypted management access.
• Least privilege — the runtime runs as the unprivileged wso2 system account, never as root.

Support

cloudimg provides 24/7 technical support for this AMI via email and live chat, covering deployment, integration artifact packaging and hot deployment, management API and credential administration, TLS termination and JVM tuning. Email support@cloudimg.co.uk or reach us via live chat. For any issues, including requesting refunds, contact support@cloudimg.co.uk.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.