Chapter 6: Development Setup and Tools

Overview

This chapter covers installing WSO2 products, setting up the development environment, and using the tools you need to build integration solutions.

Prerequisites

# Verify Java
java -version
# openjdk version "17.0.8" 2023-07-18

# Set JAVA_HOME
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
export PATH=$JAVA_HOME/bin:$PATH

Installing WSO2 Products

API Manager

# Download
wget https://github.com/wso2/product-apim/releases/download/v4.2.0/wso2am-4.2.0.zip
unzip wso2am-4.2.0.zip
cd wso2am-4.2.0

# Start
./bin/api-manager.sh

# Verify (wait ~60 seconds for startup)
curl -k https://localhost:9443/carbon/admin/login.jsp

Default Ports:

Micro Integrator

wget https://github.com/wso2/micro-integrator/releases/download/v4.2.0/wso2mi-4.2.0.zip
unzip wso2mi-4.2.0.zip
cd wso2mi-4.2.0

# Start
./bin/micro-integrator.sh

# Management API
curl -k https://localhost:9164/management/apis

Identity Server

wget https://github.com/wso2/product-is/releases/download/v6.1.0/wso2is-6.1.0.zip
unzip wso2is-6.1.0.zip
cd wso2is-6.1.0

./bin/wso2server.sh
# Console: https://localhost:9443/carbon

Docker Installation

# API Manager
docker run -p 9443:9443 -p 8243:8243 -p 8280:8280 wso2/wso2am:4.2.0

# Micro Integrator
docker run -p 8290:8290 -p 8253:8253 -p 9164:9164 wso2/wso2mi:4.2.0

# Identity Server
docker run -p 9443:9443 wso2/wso2is:6.1.0

Docker Compose (full stack):

version: '3.8'
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
      - ./dbscripts:/docker-entrypoint-initdb.d

  apim:
    image: wso2/wso2am:4.2.0
    ports:
      - "9443:9443"
      - "8243:8243"
      - "8280:8280"
    volumes:
      - ./conf/deployment.toml:/home/wso2carbon/wso2am-4.2.0/repository/conf/deployment.toml
    depends_on:
      - mysql

  mi:
    image: wso2/wso2mi:4.2.0
    ports:
      - "8290:8290"
      - "9164:9164"
    volumes:
      - ./carbonapps:/home/wso2carbon/wso2mi-4.2.0/repository/deployment/server/carbonapps

volumes:
  mysql_data:

WSO2 Integration Studio

Installation

Integration Studio is the Eclipse-based IDE for building integration projects.

# Download from WSO2 website
# Available for Linux, macOS, Windows
# Extract and run:
./IntegrationStudio

Creating a Project

File → New → Integration Project
  Project Name: my-integration
  ├── ESBConfigs              # Mediation artifacts (APIs, sequences, endpoints)
  ├── CompositeExporter        # Packages everything into a .car file
  ├── ConnectorExporter        # Bundles connector dependencies
  └── RegistryResources        # Registry files (XSLT, schemas)

Project Structure

my-integration/
├── my-integration-ESBConfigs/
│   └── src/main/synapse-config/
│       ├── api/               # REST API definitions
│       ├── endpoints/         # Endpoint configs
│       ├── sequences/         # Mediation sequences
│       ├── proxy-services/    # Proxy service configs
│       ├── local-entries/     # Local entry configs
│       └── tasks/             # Scheduled tasks
├── my-integration-CompositeExporter/
│   └── pom.xml               # Build and export config
└── my-integration-ConnectorExporter/
    └── pom.xml

Building a Composite Application

Right-click CompositeExporter → Export Composite Application
  → Select artifacts to include
  → Export as .car file

From command line (Maven):

cd my-integration
mvn clean install

# Output: my-integration-CompositeExporter/target/my-integration_1.0.0.car

Deploying to Micro Integrator

# Copy .car to MI deployment directory
cp target/my-integration_1.0.0.car \
  /path/to/wso2mi-4.2.0/repository/deployment/server/carbonapps/

# MI auto-deploys on file detection (hot deployment)

VS Code Extension

For developers who prefer VS Code over the Eclipse-based Integration Studio.

# Install WSO2 MI VS Code extension
# Extensions → Search "WSO2 Micro Integrator"

# Or install from command line
code --install-extension wso2.micro-integrator

Features:

• Create integration projects
• Graphical sequence editor
• Synapse config IntelliSense
• Built-in MI runner
• Debugging support

Configuration Files

deployment.toml

The primary configuration file for all WSO2 products (TOML format, replaces multiple XML files from older versions).

API Manager Example:

[server]
hostname = "apim.example.com"
offset = 0

[super_admin]
username = "admin"
password = "admin"
create_admin_account = true

[user_store]
type = "database_unique_id"

[database.apim_db]
type = "mysql"
url = "jdbc:mysql://db:3306/apim_db?useSSL=false"
username = "wso2carbon"
password = "wso2carbon"
driver = "com.mysql.cj.jdbc.Driver"

[database.shared_db]
type = "mysql"
url = "jdbc:mysql://db:3306/shared_db?useSSL=false"
username = "wso2carbon"
password = "wso2carbon"
driver = "com.mysql.cj.jdbc.Driver"

[keystore.primary]
file_name = "wso2carbon.jks"
password = "wso2carbon"
alias = "wso2carbon"
key_password = "wso2carbon"

[transport.https.properties]
proxyPort = 443

Micro Integrator Example:

[server]
hostname = "localhost"
hot_deployment = true

[mediation]
synapse.global_timeout_interval = 120000

[[transport.http]]
listener.port = 8290
sender.warn_on_http_500 = "*"

[[transport.http]]
listener.secured_port = 8253

[keystore.primary]
file_name = "wso2carbon.jks"
password = "wso2carbon"

Port Offset

Run multiple WSO2 products on the same machine by offsetting ports.

# Product 1 (default)
[server]
offset = 0
# Ports: 9443, 8243, 8280

# Product 2 (offset by 1)
[server]
offset = 1
# Ports: 9444, 8244, 8281

# Product 3 (offset by 2)
[server]
offset = 2
# Ports: 9445, 8245, 8282

Database Setup

Production Database (MySQL)

-- Create databases
CREATE DATABASE apim_db CHARACTER SET utf8mb4;
CREATE DATABASE shared_db CHARACTER SET utf8mb4;
CREATE DATABASE identity_db CHARACTER SET utf8mb4;

-- Create user
CREATE USER 'wso2carbon'@'%' IDENTIFIED BY 'wso2carbon';
GRANT ALL ON apim_db.* TO 'wso2carbon'@'%';
GRANT ALL ON shared_db.* TO 'wso2carbon'@'%';
GRANT ALL ON identity_db.* TO 'wso2carbon'@'%';
FLUSH PRIVILEGES;

Run init scripts:

# API Manager
mysql -u wso2carbon -p apim_db < dbscripts/apimgt/mysql.sql
mysql -u wso2carbon -p shared_db < dbscripts/mysql.sql

# Identity Server
mysql -u wso2carbon -p identity_db < dbscripts/identity/mysql.sql
mysql -u wso2carbon -p identity_db < dbscripts/consent/mysql.sql

Add JDBC driver:

cp mysql-connector-j-8.0.33.jar /path/to/wso2am-4.2.0/repository/components/lib/

CLI Tools

apictl (API Controller)

Command-line tool for managing WSO2 API Manager environments.

# Install
wget https://github.com/wso2/product-apim-tooling/releases/download/v4.2.0/apictl-4.2.0-linux-amd64.tar.gz
tar xzf apictl-4.2.0-linux-amd64.tar.gz
sudo mv apictl /usr/local/bin/

# Add environment
apictl add env production \
  --apim https://apim.example.com:9443

# Login
apictl login production -u admin -p admin

# List APIs
apictl list apis -e production

# Export API
apictl export api -n PizzaShackAPI -v 1.0.0 -e production

# Import API to another environment
apictl import api -f PizzaShackAPI_1.0.0.zip -e staging

MI CLI

# Login to MI management API
mi remote login https://localhost:9164

# List deployed APIs
mi api show

# List deployed services
mi proxyservice show

# List endpoints
mi endpoint show

# Get logs
mi log-level show org.apache.synapse

Development Workflow

Typical Workflow

1. Create project in Integration Studio / VS Code
     ↓
2. Build integration artifacts (APIs, sequences, endpoints)
     ↓
3. Test locally with embedded MI runtime
     ↓
4. Build .car file (mvn clean install)
     ↓
5. Deploy to dev MI instance
     ↓
6. Test with Postman / curl
     ↓
7. Promote to staging → production

Hot Deployment

Micro Integrator watches the carbonapps directory and auto-deploys new or updated .car files.

# Drop .car file into MI
cp my-integration_1.0.0.car \
  /opt/wso2mi/repository/deployment/server/carbonapps/

# Check deployment status
curl -k https://localhost:9164/management/apis

Debugging

Enable wire logs (see all HTTP traffic):

# deployment.toml
[[logging]]
logger.synapse-transport-http-wire.name = "org.apache.synapse.transport.http.wire"
logger.synapse-transport-http-wire.level = "DEBUG"

Enable mediation debug logs:

[[logging]]
logger.synapse.name = "org.apache.synapse"
logger.synapse.level = "DEBUG"

Integration Studio Debugger:

1. Set breakpoints on mediators in the graphical editor
2. Right-click project → Debug As → WSO2 MI Debug
3. Step through mediation sequence
4. Inspect message context, properties, and payload

Testing APIs

Using curl

# Test a REST API deployed on MI
curl -v http://localhost:8290/healthcare/doctors

# POST with JSON body
curl -X POST http://localhost:8290/healthcare/appointments \
  -H "Content-Type: application/json" \
  -d '{"doctor": "Dr. Smith", "date": "2026-03-15"}'

# Test through API Gateway (with OAuth token)
curl -H "Authorization: Bearer <token>" \
  https://localhost:8243/pizzashack/1.0.0/menu

Using Postman

1. Import OpenAPI spec from Publisher Portal
2. Set environment variables:
   - gateway_url = https://localhost:8243
   - access_token = <your_token>
3. Configure SSL verification: OFF (for self-signed certs)
4. Run collection tests

Project Templates

REST API Template

<?xml version="1.0" encoding="UTF-8"?>
<api context="/myservice" name="MyServiceAPI" xmlns="http://ws.apache.org/ns/synapse">
    <resource methods="GET" uri-template="/health">
        <inSequence>
            <payloadFactory media-type="json">
                <format>{"status": "UP", "timestamp": "$1"}</format>
                <args>
                    <arg expression="get-property('SYSTEM_TIME')"/>
                </args>
            </payloadFactory>
            <respond/>
        </inSequence>
    </resource>

    <resource methods="GET" uri-template="/items">
        <inSequence>
            <call>
                <endpoint>
                    <http method="get" uri-template="http://backend:8080/api/items"/>
                </endpoint>
            </call>
            <respond/>
        </inSequence>
        <faultSequence>
            <sequence key="errorHandler"/>
        </faultSequence>
    </resource>
</api>

Error Handler Template

<sequence name="errorHandler" xmlns="http://ws.apache.org/ns/synapse">
    <log level="custom">
        <property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
        <property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>
    </log>
    <payloadFactory media-type="json">
        <format>
            {"error": true, "code": "$1", "message": "$2"}
        </format>
        <args>
            <arg expression="get-property('ERROR_CODE')"/>
            <arg expression="get-property('ERROR_MESSAGE')"/>
        </args>
    </payloadFactory>
    <property name="HTTP_SC" value="500" scope="axis2"/>
    <respond/>
</sequence>

Key Takeaways

• JDK 11+ is required; JDK 17 recommended for production
• Docker simplifies multi-product development setups
• Integration Studio (Eclipse) or VS Code extension for building artifacts
• deployment.toml is the single configuration file for all products
• Port offset allows running multiple products on one machine
• apictl CLI manages API promotion across environments
• Hot deployment in MI means no restarts for artifact updates

Next Steps

Continue to Chapter 7: API Development to learn how to create, publish, and manage APIs.