Skip to content

Quick Start Guide

Prerequisites

A Docker-compatible container runtime such as:

  • Docker Desktop (Windows / macOS)
  • Rancher Desktop (Windows / macOS)
  • Colima (macOS)
  • Docker Engine + Compose plugin (Linux)

Ensure docker and docker compose commands are available.

docker --version
docker compose version

# Download distribution.
wget https://github.com/wso2/api-platform/releases/download/gateway/v1.2.0-beta/wso2apip-api-gateway-1.2.0-beta.zip

# Unzip the downloaded distribution.
unzip wso2apip-api-gateway-1.2.0-beta.zip

cd wso2apip-api-gateway-1.2.0-beta/

# Run the one-time setup. This provisions the AES-256 at-rest encryption key,
# the router HTTPS listener certificate, and api-platform.env
./scripts/setup.sh

# Start the complete stack
docker compose up -d

# Verify gateway controller admin endpoint is running
curl http://localhost:9094/api/admin/v1/health

# Deploy an API configuration
curl -X POST http://localhost:9090/api/management/v1/rest-apis \
  -u admin:admin \
  -H "Content-Type: application/yaml" \
  --data-binary @- <<'EOF'
apiVersion: gateway.api-platform.wso2.com/v1
kind: RestApi
metadata:
  name: reading-list-api-v1.0
spec:
  displayName: Reading-List-API
  version: v1.0
  context: /reading-list/$version
  upstream:
    main:
      url: https://apis.bijira.dev/samples/reading-list-api-service/v1.0
  policies:
    - name: set-headers
      version: v1
      params:
        request:
          headers:
            - name: x-wso2-apip-gateway-version
              value: v1.0.0
        response:
          headers:
            - name: x-environment
              value: development
  operations:
    - method: GET
      path: /books
    - method: POST
      path: /books
    - method: GET
      path: /books/{id}
    - method: PUT
      path: /books/{id}
    - method: DELETE
      path: /books/{id}
EOF


# Test routing through the gateway
curl -i http://localhost:8080/reading-list/v1.0/books
curl -ik https://localhost:8443/reading-list/v1.0/books

Customizing configuration

setup.sh writes api-platform.env, which is loaded into the containers via Docker Compose env_file. To change the storage backend, connect to a control plane, or tune other settings, edit that file (or the config.toml interpolation tokens directly). See Gateway Configuration and Environment Interpolation.

Stopping the Gateway

When stopping the gateway, you have two options:

Option 1: Stop runtime, keep data (persisted APIs and configuration) 

docker compose down
This stops the containers but preserves the controller-data volume. When you restart with docker compose up, all your API configurations will be restored.

Option 2: Complete shutdown with data cleanup (fresh start) 

docker compose down -v
This stops containers and removes the controller-data volume. Next startup will be a clean slate with no persisted APIs or configuration.