Documentation

Welcome to the NUTS documentation. Choose a topic to get started:

Building & Running — prerequisites, xcaddy, building from source, the prebuilt Docker image, Docker Compose, and Make targets
Usage — full Caddyfile / JSON configuration reference, JetStream setup, EventSource client code, replay, auth, metrics, and example scenarios
Contributing — development setup, running tests, and submitting pull requests

Quick Start (Without Docker)

Build Caddy with NUTS:

xcaddy build --with github.com/ideaconnect/nuts

Start NATS with JetStream enabled:
```
nats-server -js -p 4222
```

Create a JetStream stream:

nats stream add EVENTS \
  --subjects "events.>" \
  --storage file \
  --retention limits \
  --max-msgs 10000 \
  --max-age 24h \
  --discard old

Create a Caddyfile:

:8080 {
    route /events* {
        uri strip_prefix /events
        nuts {
            nats_url nats://localhost:4222
            stream_name EVENTS
            topic_prefix events.
        }
    }
}

Run Caddy:
```
./caddy run --config Caddyfile
```

Connect from JavaScript:

const events = new EventSource('/events?topic=my-topic');

events.addEventListener('message', (e) => {
    const data = JSON.parse(e.data);
    console.log('Received:', data, 'ID:', e.lastEventId);
});

Publish a message (using the NATS CLI):

nats pub events.my-topic '{"hello": "world"}'

Quick Start (With Docker)

Pick whichever fits your workflow:

Just NATS in Docker, Caddy local:

docker run --rm -p 4222:4222 nats:2.12-alpine -js

Prebuilt NUTS Docker image (idcttech/nuts):

docker run -d \
  -p 8080:8080 \
  -e NATS_URL=nats://host.docker.internal:4222 \
  --add-host=host.docker.internal:host-gateway \
  -v ./Caddyfile:/app/Caddyfile:ro \
  idcttech/nuts:latest

Full stack with Docker Compose (from the NUTS repo):
```
docker compose up -d --build
```
This starts NATS (with JetStream) and Caddy with NUTS together.

For detailed configuration, client usage, and example scenarios, see the Usage page.

For full build and run instructions, see Building & Running.