Quick Start

This guide will help you get EvidentSource up and running quickly using the in-memory adapter for local development.

Prerequisites

• Docker or EvidentSource binary (see Installation Guide)
• Java 17+ (for JVM client examples)

Start the Server

Option 1: Using Docker

# Run the development server (in-memory storage)
docker run -p 8080:8080 evidentsource/evidentsource-dev:latest

The server will start on http://localhost:8080.

Note

The public Docker image is for development and learning only. It uses in-memory storage—all data is lost when the container stops. For production, deploy via AWS Marketplace.

Option 2: Using Binary

# Start the server (after installation)
evident-source-server --scheme http in-memory

Create Your First Database

Using the Web UI

1. Open http://localhost:8080 in your browser
2. Click “Create Database”
3. Enter a database name (e.g., “mydb”)
4. Click “Create”

Using the gRPC API

Using the Kotlin client:

import com.evidentdb.client.EvidentDbClient

val client = EvidentDbClient("localhost", 8080)

// Create a database
client.createDatabase("mydb")

Write Your First Events

Create and submit events using the CloudEvents format:

import com.evidentdb.client.CloudEvent
import com.evidentdb.client.Transaction
import java.util.UUID

// Create an event
val event = CloudEvent(
    id = UUID.randomUUID().toString(),
    source = "quickstart-app",
    type = "UserCreated",
    subject = "user-123",
    data = mapOf(
        "username" to "alice",
        "email" to "alice@example.com"
    )
)

// Submit the event
val transaction = Transaction(events = listOf(event))
val result = client.transact("mydb", transaction)

println("Event stored at revision: ${result.revision}")

Query Events

Query by Stream

Get all events from a specific source:

val query = EventQuery(
    eventSelection = EventSelection(
        selectors = listOf(
            EventSelector(stream = "quickstart-app")
        )
    )
)

val events = client.queryEvents("mydb", query)
events.forEach { event ->
    println("${event.type}: ${event.data}")
}

Query by Subject

Get all events for a specific entity:

val query = EventQuery(
    eventSelection = EventSelection(
        selectors = listOf(
            EventSelector(subject = "user-123")
        )
    )
)

val userEvents = client.queryEvents("mydb", query)

Create a State View

State Views are WebAssembly components that transform events into queryable state. You can obtain pre-built State View components from:

• The EvidentSource component library (included with your license)
• Build your own using our SDK (documentation available in customer portal)
• Commission custom components from our professional services team

Deploy a State View

Here’s how to deploy a pre-built event counter State View:

// Load a pre-built component from the component library
val wasmBytes = loadComponentFromLibrary("event-counter-v1.wasm")

val stateView = StateViewDefinition(
    name = "event-counter",
    description = "Counts events by type",
    eventSelection = EventSelection(
        selectors = listOf(
            EventSelector() // Select all events
        )
    ),
    wasmComponent = wasmBytes
)

client.defineStateView("mydb", stateView)

Query the State View

# Get the current count
curl http://localhost:8080/databases/mydb/state-views/event-counter

# Response:
{
  "total_events": 42,
  "events_by_type": {
    "UserCreated": 10,
    "OrderCreated": 25,
    "PaymentReceived": 7
  }
}

Next Steps

Explore Example Applications

Example applications demonstrating EvidentSource patterns are available in your customer portal:

• Order Processing: Event sourcing for e-commerce
• Inventory Management: Bi-temporal tracking
• Financial Ledger: Audit-compliant transaction processing

Deploy with AWS

For production deployment, see our AWS Deployment Guide or use the AWS Marketplace listing for one-click deployment.

Learn More

• Installation Guide - Detailed setup instructions
• Core Concepts - Understand the fundamentals
• API Reference - Complete API documentation
• Component Library - Pre-built State Views and State Changes

Troubleshooting

Port Already in Use

If port 8080 is taken, specify a different port:

# With binary
evident-source-server --scheme http --port 8081 in-memory

# With Docker
docker run -p 8081:8080 evidentsource/evidentsource-dev:latest

Connection Refused

Ensure the server is running and accessible:

# Check if server is listening
curl http://localhost:8080/health

# Should return: OK

Out of Memory

For large workloads, increase memory limits:

# For Docker
docker run -m 2g evidentsource/evidentsource-dev:latest

# For binary, set system limits
ulimit -m 2097152  # 2GB

Getting Help

• Customer Support: support@evidentsource.com
• Documentation: You’re reading it!
• Customer Portal: customers.evidentsource.com