Self-Hosting
NoLag runs entirely on infrastructure you control. The broker, kraken, is part of every setup. What changes between setups is where kraken gets its answer to one question: is this token valid, and what may it reach?
Three setups
1. The broker on its own
kraken with its default static auth backend: one container, no database. Tokens and their grants live in a JSON file that kraken reloads when the file changes.
This is what the Quick Start runs. It suits development, demos, internal tools, and deployments with a fixed set of services and devices. Every new token means editing the file, and there are no short-lived browser tokens. See Static Auth File.
2. The broker and your own auth service
kraken with the http auth backend, pointed at a service you write. kraken calls it on connect, every ten minutes or so for each live connection, and optionally when a client subscribes to something new. Your service answers from your own user store with the actor's identity and grants. Three JSON endpoints are the whole contract. See HTTP Auth Contract.
3. The full stack with @nolag/core
kraken with the http backend pointed at a host that mounts @nolag/core, backed by Postgres. Core supplies the full model: projects, apps with open or restricted access, rooms (public or private), lobbies, access scopes for tenant isolation, actor tokens, and signing keys for client tokens. Projects are created from a project document and can be exported again.
The nolag-core repository runs all of it on your machine with one script. See Full Stack.
Which one
| Broker only | Broker and your auth | Full stack | |
|---|---|---|---|
| You run | kraken | kraken and your service | kraken, a host with @nolag/core, Postgres |
| Tokens come from | auth.json | Your service | Core: actor tokens and client tokens |
| Grants | Per token, in the file | Whatever your service returns | Apps, rooms, grants and access scopes |
| Browser tokens (JWT) | No | If your service verifies them | Yes |
| Grant changes reach live connections | At revalidation, within about 10 minutes | At revalidation | At revalidation, and at once for subscribes to new rooms |
| Database | None | Yours | Postgres |
| You write | A JSON file | An HTTP service | Your own host, or the example host behind your own authentication |
What every setup shares
- The same clients. The wire protocol and SDKs are identical across all three. A client needs only the broker URL and a token.
- The same broker limits. 50 publishes per second per connection and a 921,600 byte payload ceiling, fixed in the code whatever the backend says. See Configuration.
- TLS at your edge. kraken speaks plain
ws://; a reverse proxy in front of it terminates TLS. See the Production Checklist. - Scaling. Clustering several kraken nodes, or handing fan-out to an external MQTT broker, works the same in every setup. See Scaling and MQTT.
- Plugins. Auth is one of seven pluggable slots in kraken. See Plugins.
Licences
kraken and @nolag/core are Apache-2.0. The client SDKs and the JavaScript Blueprint SDKs are MIT.
Contributing
The two server repositories have different policies, each set out in its CONTRIBUTING.md:
- kraken welcomes code contributions. New backend implementations are the most useful kind (a store for Postgres or Redis, a broker for NATS or Redis pub/sub, an auth backend for JWT or JWKS), along with bug fixes that come with a failing test. Changes must keep the wire protocol backward compatible, so existing SDKs keep working.
- nolag-core accepts issues, not code. It does not take external code contributions, because there is no contributor agreement in place. Bug reports are welcome, especially any authorization decision that looks wrong, as are questions and reports of what a self-hosted deployment is missing. Forks are fine under Apache-2.0. Report security problems by email to security@nolag.app, not in a public issue.