@enbox/dwn-server

@enbox/dwn-server is a standalone HTTP + WebSocket server that hosts Decentralised Web Nodes (DWNs) for multiple tenants. It implements the DWN specification and is designed to run as a long-lived service — in Docker, on bare metal, or in a cloud environment.

Quick start

Docker (recommended)

docker run -d \
  --name dwn-server \
  -p 3000:3000 \
  -e DWN_STORAGE=level://data \
  -v dwn-data:/data \
  ghcr.io/enboxorg/dwn-server:latest

From source

git clone https://github.com/enboxorg/enbox.git
cd enbox
bun install
bun --filter @enbox/dwn-server start

Verify

curl http://localhost:3000/health
# {"ok":true}

curl http://localhost:3000/info
# {"server":"@enbox/dwn-server","version":"...","sdkVersion":"...","webSocketSupport":true,...}

Configuration

All configuration is via environment variables. There are no CLI flags.

Server

Storage

Storage URLs use a scheme prefix to select the backend:

You can point different stores at different backends — for example, keep messages in PostgreSQL but store blobs on the filesystem with LevelDB.

PostgreSQL pool tuning

When multiple stores share the same PostgreSQL connection URL, a single shared pool is used instead of one pool per store (which would be 4 pools x 10 connections = 40 connections by default).

Tenant registration

By default, any DID can use the server (open registration). You can require registration via Proof-of-Work, Provider Auth (OAuth), or both.

Provider Auth (OAuth)

For paid or managed DWN hosting, Provider Auth gates registration behind an OAuth flow:

Admin API

The admin API is disabled by default. Set DWN_ADMIN_TOKEN to enable it.

Quotas

Per-tenant storage quotas limit resource usage. Defaults are unlimited; per-tenant overrides are managed via the admin API.

Rate limiting

Audit log

Record delivery and forwarding

HTTP endpoints

WebSocket

When DS_WEBSOCKET_SERVER=on (the default), the server accepts WebSocket upgrades on the root path (/). The WebSocket transport supports:

• JSON-RPC DWN messages (same as HTTP)
• Real-time subscription events
• Flow control via rpc.ack messages (controlled by DWN_MAX_IN_FLIGHT)

Registration routes

When Proof-of-Work or Provider Auth is enabled, additional routes are exposed for tenant registration and terms-of-service acceptance.

Production deployment

PostgreSQL example

docker run -d \
  --name dwn-server \
  -p 3000:3000 \
  -e DWN_STORAGE=postgres://dwn:secret@db:5432/dwn \
  -e DWN_BASE_URL=https://dwn.example.com \
  -e DWN_ADMIN_TOKEN=your-secret-token \
  -e DWN_RATE_LIMIT_REQUESTS_PER_SECOND=30 \
  -e DWN_QUOTA_MAX_STORAGE_BYTES=1073741824 \
  ghcr.io/enboxorg/dwn-server:latest

Split storage

Store messages and state in PostgreSQL, but keep large binary data on the filesystem:

DWN_STORAGE_MESSAGES=postgres://dwn:secret@db:5432/dwn
DWN_STORAGE_DATA=level:///mnt/blobs
DWN_STORAGE_STATE_INDEX=postgres://dwn:secret@db:5432/dwn

Health checks

Use the /health endpoint for container orchestration liveness probes:

# docker-compose.yml
services:
  dwn:
    image: ghcr.io/enboxorg/dwn-server:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3