From 6d91fdbfb116357b2496ebfbf65e29ca4ab59693 Mon Sep 17 00:00:00 2001 From: EugeneTes Date: Wed, 26 Aug 2026 07:12:09 +0000 Subject: [PATCH] Document volcanic-agents user and local credentials cache in CLAUDE.md --- CLAUDE.md | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5dea7b5..2a7a25e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,10 +15,26 @@ Coolify's non-secret app config (project/server UUIDs, name, domain) lives in `d ## Connection details (for agents managing this NATS) -Both are populated from the two env vars set on the Coolify application: +There are two users, both admin (unrestricted publish/subscribe): -- `NATS_USER` — admin username (default: `admin`) -- `NATS_PASSWORD` — admin password (generated at deploy time, stored in the Coolify app's env vars) +- `admin` — user/password auth. Env vars `NATS_USER` / `NATS_PASSWORD` on the Coolify application. +- `volcanic-agents` — token auth. Env var `NATS_VOLCANIC_AGENTS_TOKEN` on the Coolify application. + +### Local credentials cache + +A **gitignored** `credentials.local.json` at the repo root mirrors the live values for quick local access. Shape: + +```json +{ + "url": "wss://nats.tes.gd", + "users": { + "admin": { "user": "…", "password": "…", "note": "…" }, + "volcanic-agents": { "user": "volcanic-agents", "token": "…", "note": "…" } + } +} +``` + +Read from it with `jq`, e.g. `jq -r '.users["volcanic-agents"].token' credentials.local.json`. It is **not** the source of truth — Coolify env vars are. Regenerate it from Coolify with the snippet below if it's stale or missing. The current live values are printed by: @@ -94,7 +110,7 @@ asyncio.run(main()) - `8080` — WebSocket listener, `no_tls: true`. The only port in `expose:`. Traefik terminates TLS and forwards `ws://nats:8080` from `wss://nats.tes.gd`. - `8222` — HTTP monitoring (`/healthz`, `/varz`, `/jsz`), used by the compose healthcheck; not routed publicly. - **JetStream**: enabled, persisted to the named volume `nats-data` mounted at `/data`. Limits: 256MB memory / 4GB file. Bump `max_file_store` in `nats-server.conf` if you need more. -- **Auth**: a single user, whose name and password come from the `NATS_USER` / `NATS_PASSWORD` env vars. Substitution happens at Docker Compose parse time (the config lives inline in `docker-compose.yml` under `configs.nats-conf.content`), so NATS itself sees a static config. No accounts, no operator/JWT mode. +- **Auth**: two users in `authorization.users` — `admin` (user/password from `NATS_USER` / `NATS_PASSWORD`) and `volcanic-agents` (token from `NATS_VOLCANIC_AGENTS_TOKEN`). Both are unrestricted (no `permissions` block → admin). Substitution happens at Docker Compose parse time (the config lives inline in `docker-compose.yml` under `configs.nats-conf.content`), so NATS itself sees a static config. No accounts, no operator/JWT mode. ## Managing / redeploying @@ -117,5 +133,6 @@ To add a second user (e.g. a scoped app account), edit the `authorization.users` | File | Purpose | |---|---| | `docker-compose.yml` | Single `nats` service, exposes 4222/8080/8222 internally; only 8080 is routed publicly via `SERVICE_FQDN_NATS_8080` + Coolify's `docker_compose_domains`. The NATS config lives inline under `configs.nats-conf.content` (delivered to the container as `/etc/nats/nats-server.conf`) — no separate config file, no bind mount (Coolify's compose executor rewrites relative host paths into a persistent app dir and can't materialise a source file for them). | -| `.gitignore` | Keeps `deploy.json` out of git. | +| `.gitignore` | Keeps `deploy.json` and `credentials.local.json` out of git. | | `deploy.json` (local only) | Coolify app config used by the `deploying-to-coolify-via-api` skill. | +| `credentials.local.json` (local only) | Cached NATS connection details for both users (WS URL, admin user/password, volcanic-agents token). Mirrors the Coolify env vars; regenerate from the API if stale. |