Documentation

Getting Started

Symbient Spine is designed to be up and running in minutes. This guide will walk you through installation, configuration, and your first integration.

Installation

Choose your preferred installation method:

Docker (Recommended)

docker pull lucuslabs/spine:latest
docker run -p 8080:8080 -p 1883:1883 -p 9001:9001 lucuslabs/spine:latest

Cloud

https://[your subdomain].symbient.io/config

Local (Ubuntu)

sudo dpkg -i spine_1.0.0_amd64.deb

Quick Start: Your First Route

Let's create a simple route that forwards HTTP requests from one service to another.

Step 1: Create a Route Configuration

{
  "route": {
    "id": "order-to-inventory",
    "name": "Order Service to Inventory",
    "from": {
      "protocol": "http",
      "endpoint": "http://order-service:8080/api/orders",
      "method": "POST"
    },
    "to": {
      "protocol": "http",
      "endpoint": "http://inventory-service:8080/api/reserve",
      "method": "POST"
    },
    "transform": {
      "type": "json-to-json",
      "mapping": {
        "productId": "item.sku",
        "quantity": "item.quantity",
        "customerId": "customer.id"
      }
    }
  }
}

Step 2: Deploy the Route

Deploy via the web console, REST API, or configuration file:

curl -X POST http://localhost:8080/config/api/save \
  -H "Content-Type: application/json" \
  -u "[your username]:[your password]" \
  -d @order-route.json

Step 3: Test Your Route

Send a test message and watch it flow through Spine:

curl -X POST http://localhost:8080/api/order-to-inventory \
  -H "Content-Type: application/json" \
  -u "[your username]:[your password]" \
  -d '{"item": {"sku": "ABC123", "quantity": 5}, "customer": {"id": "C001"}}'

Configuration

Spine can be configured through multiple methods to suit your workflow:

Configuration File (YAML)

spine:
  server:
    port: 8080
    websocket-port: 9001
    mqtt-port: 1883
  
  routes:
    - id: customer-sync
      from:
        protocol: http
        path: /api/customers
      to:
        protocol: mqtt
        topic: customers/updates
      
  security:
    enabled: true
    auth-type: jwt
    
  monitoring:
    metrics: true
    tracing: true

Environment Variables

SPINE_SERVER_PORT=8080
SPINE_WEBSOCKET_PORT=9001
SPINE_MQTT_PORT=1883
SPINE_SECURITY_ENABLED=true

REST API

Manage configuration programmatically through the REST API.

Supported Protocols

HTTP/REST

Full support for RESTful APIs with all HTTP methods, headers, and authentication schemes.

MQTT

Connect to MQTT brokers for IoT and messaging scenarios. Supports QoS levels 0, 1, and 2.

WebSocket

Bidirectional real-time communication for interactive applications.

JMS

Java Message Service integration for enterprise messaging.

Custom Protocols

Extend Spine with custom protocol adapters using our plugin system.

Message Routing

Spine provides powerful routing capabilities:

Content-Based Routing

{
  "route": {
    "id": "order-router",
    "from": "orders-queue",
    "routes": [
      {
        "when": "$.amount > 1000",
        "to": "high-value-orders"
      },
      {
        "when": "$.region == 'EU'",
        "to": "eu-processing"
      },
      {
        "otherwise": "standard-processing"
      }
    ]
  }
}

Load Balancing

Distribute messages across multiple endpoints with round-robin, random, or weighted strategies.

Error Handling

Automatic retry logic with exponential backoff and dead letter queues.

Message Transformations

Transform messages between different formats and structures:

JSON to JSON

Map fields between JSON structures with JSONPath expressions.

XML to JSON

Convert between XML and JSON formats seamlessly.

Custom Transformations

Use JavaScript or Groovy for complex transformation logic.

{
  "transform": {
    "type": "javascript",
    "script": "return { fullName: data.firstName + ' ' + data.lastName };"
  }
}

Monitoring & Observability

Keep track of your integrations with built-in monitoring:

Metrics

• Message throughput and latency
• Success and error rates
• Resource utilization

Distributed Tracing

Track messages across your entire integration flow with OpenTelemetry support.

Logs

Structured logging with correlation IDs for easy troubleshooting.

Dashboards

Real-time dashboards in the web console show system health and performance.