/drasi

Drasi Server bundle

Use this bundle for Drasi Server standalone runtime features: Web UI, REST API, YAML configuration, Solution Templates, Instances, plugin system, VS Code Extension, webhook mode, state stores, and Docker/source deployment.

When to use

• Deploying Drasi Server via Docker, Docker Compose, or building from source
• Using the Web UI to manage data pipelines visually
• Configuring sources, queries, and reactions via YAML files or REST API
• Using Solution Templates for quick pipeline deployment
• Managing Instances for multi-tenant or environment isolation
• Installing, upgrading, or managing plugins via OCI registry
• Receiving webhook events from third-party services (GitHub, Stripe)
• Using the VS Code Extension for integrated development

Runtime form

Drasi Server is a standalone single-process runtime, no Kubernetes required. It runs as a Docker container or native binary with an embedded Web UI, REST API, and plugin host.

Quick start

Drasi Server ships as a single-process binary and a container image. There is no Drasi Server docker-compose.yml in the upstream repo, the official getting-started runs the binary directly (./bin/drasi-server --config getting-started.yaml) and only uses docker compose for the tutorial database, not for the server. In production, pin the image to an immutable digest; do not use the floating latest tag (see ../../SKILL.md "Prerequisites by runtime").

# Container (resolve to an immutable digest first; do not use a floating tag in production)
docker run --rm -p 8080:8080 ghcr.io/drasi-project/drasi-server@sha256:<digest>
curl http://localhost:8080/health

# Or run the pinned binary against a config file
./bin/drasi-server --config getting-started.yaml

# Web UI
open http://localhost:8080/ui/

# OpenAPI / interactive docs (verified against drasi.io getting-started)
open http://localhost:8080/api/v1/docs/

# Tip: GitHub releases also ship drasi-sse-cli, a companion binary that streams query
# change events over SSE from the command line — useful for smoke-testing reactions
# without a browser or custom client.

YAML configuration

apiVersion: drasi.io/v1
id: my-server
host: 0.0.0.0
port: 8080
logLevel: info
enableUi: true
persistConfig: true
persistIndex: false

plugins:
  - ref: source/postgres:0.1.8
  - ref: reaction/sse

sources:
  - kind: postgres
    id: my-postgres
    autoStart: true
    host: localhost
    port: 5432
    database: mydb
    user: postgres
    password: ${DB_PASSWORD}
    tables: [orders, customers]

queries:
  - id: high-value-orders
    query: "MATCH (o:Order) WHERE o.amount > 1000 RETURN o"
    queryLanguage: Cypher
    sources:
      - sourceId: my-postgres
    autoStart: true

reactions:
  - kind: log
    id: logger
    queries:
      - high-value-orders
    autoStart: true

Web UI

The Web UI provides a visual flow canvas for managing pipelines:

• Green nodes = Sources, Blue nodes = Queries, Purple nodes = Reactions
• Animated edges show data flow direction
• Inspector panels show component status, config, and connected components
• Activity feed shows real-time component events (SSE)
• Theme toggle for light/dark mode

Access at http://localhost:8080/ui. Disable with --disable-ui or enableUi: false.

Solution Templates

Pre-configured component sets deployable with a single action:

# Via Web UI: + Add → Solutions → browse gallery
# Via API:
curl -X POST http://localhost:8080/api/v1/instances/default/solutions \
  -H "Content-Type: application/json" \
  -d '{"templateId": "iot-temperature-monitor", "variables": {"TEMP_THRESHOLD": "80"}}'

Built-in templates include simple-log-pipeline and iot-temperature-monitor. Create custom templates from existing instances via the Web UI.

Instances

Isolated processing environments within one Drasi Server:

# Create instance
curl -X POST http://localhost:8080/api/v1/instances \
  -H "Content-Type: application/json" \
  -d '{"id": "staging"}'

# Instance-specific API routes
curl http://localhost:8080/api/v1/instances/staging/sources
curl http://localhost:8080/api/v1/instances/staging/queries
curl http://localhost:8080/api/v1/instances/staging/snapshot

Use for: multi-tenant deployments, environment isolation (dev/staging/prod), modular architectures.

Component catalog (plugins)

Drasi Server capabilities are delivered as plugins installed from OCI registries (default ghcr.io/drasi-project). Server/lib use lowercase kind strings, unlike the PascalCase kinds in Drasi for Kubernetes (postgres here vs PostgreSQL there) ; never port kinds between runtimes. Catalog per the authoritative drasi-context.yaml (0.7.0, checked 2026-08-16):

A few components are built in (application source/reaction, noop bootstrap, rocksdb index, redb state store); everything else installs via drasi-server plugin install. For per-source/reaction configuration, use the how-to guides at https://drasi.io/drasi-server/how-to-guides/ (Configure Sources / Configure Reactions / Configure Bootstrap Providers / Configure Identity Providers / Configure Secret Stores). Sources and reactions ship as separate crates on crates.io (e.g. drasi-source-postgres, drasi-reaction-http) ; pin crate versions explicitly when embedding instead of using the server.

There is no single monolithic Drasi version for drasi-lib / Drasi Server: the engine and every Source/Reaction/Bootstrap/infra plugin are released and versioned independently (semver) on crates.io and as OCI images at ghcr.io/drasi-project; Drasi for Kubernetes is a separate platform release train (per the authoritative drasi-context.yaml, verified 2026-08-16). The server records resolved plugin versions in a plugins.lock lockfile; commit it alongside the config for reproducible deployments.

Bootstrap providers as top-level components (server PR #136, shipped in the 0.2.x line): bootstrap providers can be declared once as a server/instance-level bootstrapProviders: list ({ kind, id, ...config }) and referenced by sources via bootstrapProvider: <id>, mirroring how identity providers work. The inline form still works unchanged (backward compatible), and an inline bootstrapper of the same kind as its source inherits all un-overridden source config. Validation rejects dangling references, missing ids, and duplicate ids at startup. Config-only (no REST CRUD for providers themselves); multiple sources referencing one top-level entry each get their own provider instance from the shared config.

Plugin system

# Install from OCI registry
drasi-server plugin install source/postgres:0.1.8

# Install from local file
drasi-server plugin install file:///opt/drasi/libdrasi_source_custom.so

# Upgrade all
drasi-server plugin upgrade --all

# List installed
drasi-server plugin list

# Verify signatures (cosign/Sigstore)
# Built-in when verifyPlugins: true in config

Webhook mode (HTTP Source)

Receive events from third-party services:

sources:
  - kind: http
    id: github-webhook
    autoStart: true
    host: 0.0.0.0
    port: 9000
    webhooks:
      errorBehavior: reject
      routes:
        - path: /github/events
          methods: [POST]
          auth:
            signature:
              type: hmac-sha256
              secretEnv: GITHUB_WEBHOOK_SECRET
              header: X-Hub-Signature-256
          mappings:
            - when:
                header: X-GitHub-Event
                equals: push
              elementType: node
              operation: insert
              template:
                id: "commit-{{payload.head_commit.id}}"
                labels: ["Commit"]
                properties:
                  message: "{{payload.head_commit.message}}"

REST API surface

Note: Drasi Server does not currently support in-place editing via REST, delete and re-create to modify components.

CLI commands

drasi-server                          # Run with default config
drasi-server --config path/to.yaml    # Run with specific config
drasi-server init --output config.yaml # Interactive config creation
drasi-server validate --config config.yaml  # Validate without starting
drasi-server doctor                   # Check system dependencies

Environment variables

Auto-loads .env files from the config file directory.

State store options

WAL (write-ahead log) is always enabled at ./data/<instance>/wal/.

Persistent-index archive is opt-in (server PR #152/#139, 0.2.2 line): enable_archive for the persistent index provider defaults to false: the archive column family is double-written on every element update and only temporal queries read it, so most queries were paying a write cost they never used. Enable it only when you actually run temporal reads against the persistent index; with archive disabled, temporal reads fail with a clear error (fixed upstream in drasi-core#699) rather than silently returning wrong results. Verify this default against your pinned server version; pre-0.2.2 lines archived by default.

Drasi Server vs Drasi for Kubernetes

Validation

Infrastructure success (the container is running) is not acceptance. Prove the full source → query → reaction chain before sign-off.

Record the runtime form (Drasi Server), the pinned image digest, and the reaction-delivery evidence in the PR or release notes per ../../SKILL.md "Evidence required before success". For destructive changes (delete/recreate a component, since Drasi Server has no in-place REST edit), follow the controls in ../recovery/guide.md.

Related bundles

• security. Auth, network, secrets
• operations. Runtime triage and drift checks
• recovery. Destructive-change controls (Server has no in-place REST edit)
• currency-and-ai-context. Version pins and drift control