From c1573a2b9538eedc7c79e7687cf672a83b58cc8b Mon Sep 17 00:00:00 2001 From: EugeneTes Date: Wed, 26 Aug 2026 15:19:21 +0000 Subject: [PATCH] Document NATS per-user token gotcha and Coolify deploy-status vs runtime-health distinction --- CLAUDE.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 27b88bf..20754d0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -128,6 +128,12 @@ Rotating the password: PATCH the `NATS_PASSWORD` env on the Coolify app, then re To add a second user (e.g. a scoped app account), edit the `authorization.users` array in the `configs.nats-conf.content` block in `docker-compose.yml`, and set any new credential env vars in Coolify. +## Gotchas learned the hard way + +- **No per-user `token` field in NATS config.** `authorization.users = [...]` entries only accept `user+password`, `nkey`, or JWT — a `token` key inside a users entry makes `nats-server` refuse to start with `unknown field "token"`. The `token` key is only valid at the **top level** of `authorization`, and it defines a single server-wide token (mutually exclusive with `users`). To give a specific user a bearer-token-style credential, put the random token in the `password` field. On the wire it's the standard NATS user/password auth mechanism; only the semantics (opaque random string vs. human-picked password) differ. + +- **Coolify's deploy status ≠ container health.** A deploy returning `status: "finished"` from `/api/v1/deployments/…` just means the build + `docker compose up -d` step ran to completion. If the container then crash-loops (e.g. bad `nats-server.conf`), the deploy is still "finished" but the app's `/api/v1/applications/{uuid}` shows `status: "restarting:unknown"` and `/api/v1/applications/{uuid}/logs` returns `Application is not running.` — no runtime logs via API. Fall back to `docker logs ` on the Coolify host to see why the process is dying. Container name pattern: `nats--`. + ## Files in this repo | File | Purpose |