Quick Start Guide

Get WIXY running in under a minute. This guide covers installation, first launch, and creating your first stub.

Prerequisites

Requirement	Version	Purpose
Java	21+ (LTS)	Runtime
Gradle	9.x (bundled)	Build system
Docker	24+ (optional)	Container deployment

Option 1 — Local Start (Recommended)

# Clone the repository
git clone https://github.com/vinipx/wixy.git
cd wixy

# Start locally (builds and runs with local profile)
./scripts/start-local.sh

This will:

1. Build the project (skipping tests for speed)
2. Start Spring Boot on port 8080 (Admin API + Actuator)
3. Start embedded WireMock on port 9090 (Stub Server)

Option 2 — Docker Start

# Clone and start with Docker
git clone https://github.com/vinipx/wixy.git
cd wixy

# Build and run Docker container
./scripts/start-docker.sh

# Or use Docker Compose (includes proxy config)
docker-compose up

Option 3 — Gradle Direct

# Build the project
./gradlew build

# Run with default profile
./gradlew bootRun

# Run with specific profile
./gradlew bootRun --args='--spring.profiles.active=local'

Verify Installation

Once WIXY is running, verify all endpoints are accessible:

# Health check — should return {"status":"UP"}
curl http://localhost:8080/actuator/health

Access the Dashboard

Open your browser at http://localhost:8080.

WIXY Hub provides a modern dashboard to:

• Manage Registry: Add remote servers and switch engines.
• Control Engine: Toggle proxy and recording at runtime.
• Monitor Stubs: View and manage active mappings in real-time.

Try the APIs

Interactive API documentation is also available:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI Spec: http://localhost:8080/v3/api-docs

Create Your First Stub

Step 1 — Define the Stub

curl -X POST http://localhost:8080/wixy/admin/mappings \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "method": "GET",
      "urlPath": "/api/users/1"
    },
    "response": {
      "status": 200,
      "jsonBody": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }'

Step 2 — Hit the Stub

curl http://localhost:9090/api/users/1

Response:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

Step 3 — Verify It's Listed

curl http://localhost:8080/wixy/admin/mappings

Step 4 — Clean Up

# Delete a specific stub by ID
curl -X DELETE http://localhost:8080/wixy/admin/mappings/{id}

# Or reset all stubs
curl -X POST http://localhost:8080/wixy/admin/mappings/reset

Port Reference

Port	Service	Purpose
8080	Spring Boot	Admin API, Actuator, Swagger UI
9090	WireMock	Stub server — send test traffic here

tip

Both ports are fully configurable via environment variables. See the Configuration guide for details.

What's Next?

• Architecture Overview — Understand how WIXY components interact
• Stub Management — Deep dive into stub CRUD operations
• Proxy Mode — Forward traffic to upstream services
• Recording — Capture and replay real traffic
• Testing — Unit tests, integration tests, and coverage strategy
• Running Locally — All methods for running and testing locally
• API Reference — Complete endpoint documentation