feat(hosting): default self-hosted realtime streams to v2 (s2-lite) (#4185)
## Summary Realtime streams (AI-agent token streaming and run streams) now default to v2 for self-hosters, backed by a bundled [s2-lite](https://s2.dev) service. Self-hosting previously shipped no S2 configuration, so streams ran on the Redis-backed v1 path and there were no docs for wiring up v2. Both the Docker Compose stack and the Helm chart now provision s2-lite with persistent storage and set the stream env vars out of the box. ## What's included - **Docker Compose**: a persistent `s2` service (s2-lite), a basin init spec, and the `REALTIME_STREAMS_S2_*` plus `REALTIME_STREAMS_DEFAULT_VERSION=v2` env on the webapp. `.env.example` documents the v1 fallback and hosted-S2 options. - **Helm**: an `s2` StatefulSet, PVC, Service and ConfigMap (runs as the non-root image user via `fsGroup`), an `s2` values block, and webapp env wiring with an existing-secret path for hosted S2. - **Docs**: the `REALTIME_STREAMS_S2_*` and `REALTIME_STREAMS_DEFAULT_VERSION` vars in the webapp env reference, plus a "Realtime streams" section in the Docker and Kubernetes self-hosting guides. ## Notes - The OSS code default stays `v1`; v2 becomes the default purely through the self-hosting artifacts, so non-self-host deployments are unaffected. Disabling s2, or setting the version back to `v1`, cleanly reverts to Redis-backed v1. - With v2 enabled, the bundled s2 service is a required dependency for streaming: if it is down, streams error while the task itself still runs. That is the intended trade for the better v2 path. - You can point at a hosted S2 at s2.dev instead of the bundled server.
This commit is contained in:
Matt Aitken
@@ -354,6 +354,27 @@ EVENT_REPOSITORY_DEFAULT_STORE=clickhouse_v2
|
||||
|
||||
This only affects new runs; existing runs continue to read from wherever their events were originally stored.
|
||||
|
||||
## Realtime streams
|
||||
|
||||
Realtime streams power AI-agent token streaming and run streams. They default to **v2**, backed by the bundled `s2` service — [s2-lite](https://s2.dev), the open-source, self-hostable S2 server. It stores stream data in a persistent volume and is preconfigured in the webapp compose file, so no setup is required.
|
||||
|
||||
To fall back to the Redis-backed **v1** streams, set on the webapp in your `.env`:
|
||||
|
||||
```bash
|
||||
REALTIME_STREAMS_DEFAULT_VERSION=v1
|
||||
```
|
||||
|
||||
To use a hosted S2 at [s2.dev](https://s2.dev) instead of the bundled s2-lite, point the endpoint at your basin and supply an access token:
|
||||
|
||||
```bash
|
||||
REALTIME_STREAMS_S2_BASIN=your-basin
|
||||
REALTIME_STREAMS_S2_ENDPOINT=https://your-basin.b.aws.s2.dev/v1
|
||||
REALTIME_STREAMS_S2_SKIP_ACCESS_TOKENS=false
|
||||
REALTIME_STREAMS_S2_ACCESS_TOKEN=your-access-token
|
||||
```
|
||||
|
||||
See the [webapp environment variables](/self-hosting/env/webapp) for the full list of realtime stream settings.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Deployment fails at the push step.** The machine running `deploy` needs registry access. See the [registry setup](#registry-setup) section for more details.
|
||||
|
||||
Vendored
+6
-1
@@ -139,9 +139,14 @@ mode: "wide"
|
||||
| **Task events** | | | |
|
||||
| `EVENT_REPOSITORY_DEFAULT_STORE` | No | postgres | Where to store task events. Set to `clickhouse_v2` to store in ClickHouse (recommended for production). |
|
||||
| **Realtime** | | | |
|
||||
| `REALTIME_STREAM_VERSION` | No | v1 | Realtime stream protocol version. One of `v1`, `v2`. |
|
||||
| `REALTIME_STREAM_VERSION` | No | v1 | Stream version exposed to tasks via the `TRIGGER_REALTIME_STREAM_VERSION` variable. Distinct from `REALTIME_STREAMS_DEFAULT_VERSION`. One of `v1`, `v2`. |
|
||||
| `REALTIME_STREAM_MAX_LENGTH` | No | 1000 | Realtime stream max length. |
|
||||
| `REALTIME_STREAM_TTL` | No | 86400 (1d) | Realtime stream TTL (s). |
|
||||
| `REALTIME_STREAMS_DEFAULT_VERSION` | No | v1 | Server-side default the webapp uses when a stream request doesn't pin a version (modern SDKs request `v2`). The Docker and Helm self-hosting defaults set this to `v2`. One of `v1`, `v2`. |
|
||||
| `REALTIME_STREAMS_S2_BASIN` | No | — | S2 basin that holds v2 realtime streams. Required for `v2`. Must be at least 8 characters. |
|
||||
| `REALTIME_STREAMS_S2_ENDPOINT` | No | — | Custom S2 API endpoint, including the `/v1` suffix (e.g. `http://s2/v1` for the bundled s2-lite). Omit to use hosted S2 at s2.dev. |
|
||||
| `REALTIME_STREAMS_S2_SKIP_ACCESS_TOKENS` | No | false | Skip minting per-stream access tokens. Set to `true` for s2-lite, which needs no authentication. |
|
||||
| `REALTIME_STREAMS_S2_ACCESS_TOKEN` | No | — | S2 access token. Required for hosted S2 unless `REALTIME_STREAMS_S2_SKIP_ACCESS_TOKENS` is `true`. |
|
||||
| **Bootstrap** | | | |
|
||||
| `TRIGGER_BOOTSTRAP_ENABLED` | No | 0 | Trigger bootstrap enabled. |
|
||||
| `TRIGGER_BOOTSTRAP_WORKER_GROUP_NAME` | No | — | Trigger bootstrap worker group name. |
|
||||
|
||||
@@ -375,6 +375,32 @@ webapp:
|
||||
|
||||
This only affects new runs; existing runs continue to read from wherever their events were originally stored.
|
||||
|
||||
## Realtime streams
|
||||
|
||||
Realtime streams power AI-agent token streaming and run streams. They default to **v2**, backed by the bundled `s2` deployment — [s2-lite](https://s2.dev), the open-source, self-hostable S2 server. The chart deploys it with a persistent volume, so no extra services are required.
|
||||
|
||||
To fall back to the Redis-backed **v1** streams, set the default version to `v1`:
|
||||
|
||||
```yaml
|
||||
s2:
|
||||
defaultStreamVersion: "v1"
|
||||
```
|
||||
|
||||
To use a hosted S2 at [s2.dev](https://s2.dev) instead of the bundled s2-lite, disable the bundled deployment and point at your basin. Supply the access token via an existing secret:
|
||||
|
||||
```yaml
|
||||
s2:
|
||||
deploy: false
|
||||
skipAccessTokens: false
|
||||
external:
|
||||
endpoint: "https://your-basin.b.aws.s2.dev/v1"
|
||||
existingSecret: "s2-credentials"
|
||||
existingSecretAccessTokenKey: "access-token"
|
||||
basin: "your-basin"
|
||||
```
|
||||
|
||||
To disable realtime streams v2 entirely and use v1, set `s2.deploy: false` with no external endpoint. See `helm show values` for all `s2` options.
|
||||
|
||||
## Worker token
|
||||
|
||||
When using the default bootstrap configuration, worker creation and authentication is handled automatically. The webapp generates a worker token and makes it available to the supervisor via a shared volume.
|
||||
|
||||
Reference in New Issue
Block a user