server-deployment

name: server-deployment description: > Running durable stream servers. DurableStreamTestServer for development (Node.js, @durable-streams/server, not for production), Caddy plugin for production with Caddyfile configuration, data_dir for file-backed persistence, max_file_handles tuning, long_poll_timeout, server binary downloads for macOS Linux Windows, @durable-streams/cli tool setup, conformance test runner. type: lifecycle library: durable-streams library_version: "0.2.1" sources: - "durable-streams/durable-streams:packages/caddy-plugin/README.md" - "durable-streams/durable-streams:packages/server/README.md" - "durable-streams/durable-streams:packages/cli/README.md"

Durable Streams — Server Deployment

Two server options: a Node.js development server for prototyping and a Caddy-based production server with file persistence and CDN support.

Setup

Development server (Node.js)

import { DurableStreamTestServer } from "@durable-streams/server"

const server = new DurableStreamTestServer({
  port: 4437,
  host: "127.0.0.1",
})

await server.start()
console.log(`Dev server running on ${server.url}`)

Production server (Caddy binary)

Download the binary from GitHub releases for your platform.

# Start the server
./durable-streams-server run --config Caddyfile

Caddyfile configuration:

:8787 {
  route /v1/stream/* {
    durable_streams {
      data_dir ./data
      max_file_handles 200
      long_poll_timeout 60s
    }
  }
}

Core Patterns

CLI for testing

# Install CLI
npm install -g @durable-streams/cli

# Set server URL
export STREAM_URL=http://localhost:4437

# Create, write, read
durable-stream create my-stream
durable-stream write my-stream "Hello, world!"
durable-stream read my-stream

Running conformance tests

# Against your server
npx @durable-streams/server-conformance-tests --run http://localhost:4437

# Watch mode for development
npx @durable-streams/server-conformance-tests --watch src http://localhost:4437

Programmatic dev server with stream creation

import { DurableStreamTestServer } from "@durable-streams/server"
import { DurableStream } from "@durable-streams/client"

const server = new DurableStreamTestServer({ port: 0 }) // Random port
await server.start()

// Streams must be created before clients can connect
await DurableStream.create({
  url: `${server.url}/v1/stream/my-app`,
  contentType: "application/json",
})

console.log(`Dev server running on ${server.url}`)

Programmatic dev server in tests

import { DurableStreamTestServer } from "@durable-streams/server"

const server = new DurableStreamTestServer({ port: 0 }) // Random port
await server.start()

// Run your tests against server.url

await server.stop()

Caddy configuration options

Common Mistakes

CRITICAL Using the Node.js dev server in production

Wrong:

// production deployment
import { DurableStreamTestServer } from "@durable-streams/server"
const server = new DurableStreamTestServer({ port: 4437 })

Correct:

# Use the Caddy plugin binary
./durable-streams-server run --config Caddyfile

DurableStreamTestServer is explicitly not for production. It uses in-memory storage, has no CDN integration, and is single-process only.

Source: packages/server/README.md

CRITICAL Not configuring data_dir for persistence

Wrong:

:8787 {
  route /v1/stream/* {
    durable_streams
  }
}

Correct:

:8787 {
  route /v1/stream/* {
    durable_streams {
      data_dir ./data
      max_file_handles 200
    }
  }
}

Without data_dir, the Caddy plugin uses in-memory storage. Server restarts lose all data.

Source: packages/caddy-plugin/README.md

MEDIUM Setting max_file_handles too low for production

Wrong:

durable_streams {
  data_dir ./data
  # default 100 handles — fine for dev, low for production
}

Correct:

durable_streams {
  data_dir ./data
  max_file_handles 500  # Tune based on active stream count
}

Default is 100 file handles. High-throughput deployments with many concurrent streams can exhaust the pool, causing latency spikes.

Source: packages/caddy-plugin/store/filepool.go

See also

• getting-started — Connect a client to your server
• go-to-production — CDN caching, TTL, and HTTPS for production

Version

Targets durable-streams-server v0.2.1.