NATS Core/JetStream with native operator, account and user provisioning.
844
teyfix/nats provides NATS Core, optional JetStream/WebSockets, declarative operator/account/user provisioning through NSC, generated credentials, and an optional Prometheus exporter under Process Compose.
docker buildx bake nats-smoke
docker buildx bake nats --load
mkdir -p .state/nats/{data,credentials,logs}
docker compose -f svc/nats/example/compose.yaml up -d --wait
Mount one YAML document at /config/nats.yaml (NATS_CONFIG can override the path). The example has a full-access service identity and a subject-restricted client. Names must be lowercase names with letters/digits, underscores or hyphens. Unknown fields fail validation. Changes apply on restart.
| Configuration | Default / behavior |
|---|---|
operator, server_name | teyfix |
accounts | Required nonempty list with name and users |
accounts[].users | Required nonempty list with name, publish, subscribe, deny_publish, deny_subscribe |
publish, subscribe | [">"]; empty lists explicitly deny all in that direction |
deny_publish, deny_subscribe | []; native deny permissions override allowed subjects |
jetstream.enabled | true; false disables JetStream globally |
jetstream.memory_mb, disk_mb | 256 and 16384 server limits |
accounts[].jetstream.enabled | true, subject to the global setting |
accounts[].jetstream.memory_mb, disk_mb | 64 and 1024 account limits |
accounts[].jetstream.streams, consumers | 100 each |
accounts[].signing_seed | false; explicitly export an account signing seed for an application credential issuer |
credentials.uid, gid | 1000; owner of generated account credential directories/files |
websocket.enabled | false; enables plain WebSockets on 9222 |
metrics.enabled | false; enables prometheus-nats-exporter on 7777 |
Subject patterns support literal dot-separated tokens, *, and terminal >. Supply _INBOX.> subscription permission for request/reply clients. This first contract does not expose inter-account imports/exports or queue-specific permission syntax. Application stream/consumer definitions remain with their consuming services; the image sets account limits without owning application stream initialization.
Native NSC owns operator/account keys and JWTs under /data/nsc. A native memory resolver contains the generated account JWTs; startup completes provisioning before NATS starts. No custom authentication server or JWT signing client is implemented. Preserve /data across ordinary restarts to preserve identity and JetStream data. Changing the operator name requires fresh disposable state.
Each configured user gets /credentials/<account>/<user>.creds and each account gets account.pub. Account directories are mode 0700 and files 0600, owned by credentials.uid/gid. Mount only the required credentials into each consumer. signing.seed is exported only when explicitly enabled; it can issue additional users for that account. System/operator credentials are never exported.
Unchanged user declarations retain their keys and credentials. A permission change revokes/deletes the previous user through NSC, generates a new identity, and replaces its credential file. Old credential copies stop authenticating; consumers must read the new file. Merely issuing another JWT would leave old permissions usable, so revocation is part of reconciliation.
Removing a previously managed user revokes its credentials and removes its exported file. Removing a previously managed account removes it from the resolver and removes exported credentials. JetStream files are not implicitly purged; recreating a removed account produces a new identity. Keep declarations stable unless that change is intended. Reconciliation may partially apply before an error; startup fails visibly and the next start reconciles again.
nats metric prefix./data: identities and JetStream state; .state/nats/data in consumers./credentials: generated credentials; .state/nats/credentials./var/log/nats/server.log: native timestamped text log, readable for an external Vector collector. NSC/Process Compose/exporter diagnostics remain on stdout/stderr. The image does not pretend native NATS text logs are JSON.The exporter restarts on failure under Process Compose; readiness includes its metrics endpoint when enabled. Log retention belongs to the consumer. Mount logs read-only into Vector. docker compose down -v does not erase the example's bind mounts; a scoped reset removes its .state/nats directories while stopped.
Tests execute native NATS/NSC/CLI binaries on amd64 and arm64, covering Core request/reply, account isolation, subject restrictions, credential stability and revocation, retained JetStream data, WebSockets, metrics, disabled companions, configuration errors and shutdown. Python is present only in the smoke stage.
Log directories can be overridden with paths.log in the service YAML. Native data directories remain unchanged.
A user can declare context: {url: "nats://nats.lokal:4222", creds: /nats-creds/app/service.creds}. The image writes native context JSON at /credentials/<account>/contexts/<user>.json; creds is the absolute path as seen by the consuming CLI/UI container. Mount that context directory into NUI or the CLI's contexts directory. Context files use the configured credentials UID/GID and private permissions. Removing a user or its context declaration removes the managed context file without rotating an unchanged user's credentials.
Maintained from the source documentation. See published tags and the service integration guide.
Content type
Image
Digest
sha256:e15b6ca30…
Size
94.6 MB
Last updated
4 days ago
docker pull teyfix/nats:0.1.0-build.local.20261017055747