Docker Deployment

This guide covers running EvidentSource with Docker for local development and testing only.

When to Use This Image

The development Docker image is ideal for:

Local development — Quick setup without installing dependencies
Learning — Experiment with the EvidentSource API and programming model
Testing — Run integration tests in CI/CD pipelines
Prototyping — Build proof-of-concepts before production deployment

For production workloads, deploy via AWS Marketplace which provides:

Persistent storage with DynamoDB
Event streaming via Kafka/SNS
High availability and auto-scaling
Enterprise support

Prerequisites

Docker 20.10 or later
Docker Compose (optional, for multi-container setups)

Quick Start

Pull and Run

# Pull the development server image
docker pull evidentsource/evidentsource-dev:latest

# Run the server
docker run -p 8080:8080 evidentsource/evidentsource-dev:latest

The server starts on http://localhost:8080. Open this URL to access the web UI.

Docker Compose Setup

For a more complete local development environment, use Docker Compose.

Basic Setup

Create a docker-compose.yml:

version: '3.8'

services:
  evidentsource:
    image: evidentsource/evidentsource-dev:latest
    ports:
      - "8080:8080"
    environment:
      - RUST_LOG=info
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 10s
      timeout: 5s
      retries: 3

Start the server:

docker compose up -d

With Jaeger Tracing

Add distributed tracing to understand request flow:

version: '3.8'

services:
  evidentsource:
    image: evidentsource/evidentsource-dev:latest
    ports:
      - "8080:8080"
    environment:
      - RUST_LOG=info,evident_source=debug
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317
      - OTEL_SERVICE_NAME=evidentsource-dev
    depends_on:
      - jaeger
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 10s
      timeout: 5s
      retries: 3

  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"  # Jaeger UI
      - "4317:4317"    # OTLP gRPC
    environment:
      - COLLECTOR_OTLP_ENABLED=true

Access the services:

EvidentSource: http://localhost:8080
Jaeger UI: http://localhost:16686

Configuration

Command Line Options

docker run evidentsource/evidentsource-dev:latest --help

Option	Description	Default
`--host`	Bind address	`0.0.0.0`
`--port`	Listen port	`8080`

Environment Variables

Variable	Description
`RUST_LOG`	Log level (`error`, `warn`, `info`, `debug`, `trace`)
`OTEL_EXPORTER_OTLP_ENDPOINT`	OpenTelemetry collector endpoint
`OTEL_SERVICE_NAME`	Service name for OpenTelemetry traces

Debug Logging

Enable verbose logging to understand what’s happening:

docker run -p 8080:8080 \
  -e RUST_LOG=debug \
  evidentsource/evidentsource-dev:latest

For even more detail on specific modules:

docker run -p 8080:8080 \
  -e RUST_LOG=info,evident_source=debug,evident_source::api=trace \
  evidentsource/evidentsource-dev:latest

Troubleshooting

Container Won’t Start

Check logs:

docker logs <container_id>

Common issues:

Port already in use: Change the host port mapping (-p 8081:8080)
Out of memory: Increase Docker memory limits in Docker Desktop settings

Cannot Connect

# Verify container is running
docker ps

# Check if port is exposed
docker port <container_id>

# Test connectivity
curl http://localhost:8080/health

Enable Debug Logging

If you’re experiencing issues, enable debug logging:

docker run -p 8080:8080 \
  -e RUST_LOG=debug \
  evidentsource/evidentsource-dev:latest

Image Tags

Tag	Description
`latest`	Most recent stable release
`X.Y.Z`	Specific version (e.g., `1.2.3`)

Next Steps

Learn the Programming Model

Now that you have EvidentSource running locally:

Quick Start — Create databases, write events, and query state
Event Sourcing Concepts — Understand the fundamentals
API Reference — Explore the gRPC and REST APIs
DCB Pattern — Learn about Dynamic Consistency Boundaries

Ready for Production?

When you’re ready to deploy for real workloads:

AWS Marketplace — Deploy the production server with DynamoDB storage, Kafka integration, and enterprise support