tes
acd37942e9
Coolify's compose executor rewrites relative bind mounts to a persistent app dir with no source file, causing docker to auto-create the mount target as a directory and fail with "not a directory". Delivering the config through configs.content instead avoids the rewrite entirely and lets Docker Compose substitute NATS_USER/NATS_PASSWORD at parse time.
122 lines
5.0 KiB
Markdown
122 lines
5.0 KiB
Markdown
# NATS Expert
|
|
|
|
This project deploys a NATS server behind Coolify, reachable **over WebSockets** only. NATS' native TCP port (4222) is not exposed to the outside — the WS endpoint is the sole entry point for both applications and the managing agent.
|
|
|
|
## Deployment target
|
|
|
|
- **Coolify project:** `Volcanic MFEs` (`p4fts5a0kv3tahzjtbtfequk`)
|
|
- **Server:** `localhost` (`d0c4owww4kwo0ow08wws4ss8`)
|
|
- **Build pack:** `dockercompose`
|
|
- **Compose file:** `/docker-compose.yml`
|
|
- **Public domain:** `https://nats.tes.gd` → routed by Traefik to `nats:8080` (WebSocket listener)
|
|
- **TLS:** terminated at Traefik. NATS itself runs with `no_tls: true` on the WS listener.
|
|
|
|
Coolify's non-secret app config (project/server UUIDs, name, domain) lives in `deploy.json` at the repo root and is **gitignored** — it is regenerated locally when needed by the `deploying-to-coolify-via-api` skill flow.
|
|
|
|
## Connection details (for agents managing this NATS)
|
|
|
|
Both are populated from the two env vars set on the Coolify application:
|
|
|
|
- `NATS_USER` — admin username (default: `admin`)
|
|
- `NATS_PASSWORD` — admin password (generated at deploy time, stored in the Coolify app's env vars)
|
|
|
|
The current live values are printed by:
|
|
|
|
```bash
|
|
: "${COOLIFY_URL:?}" "${COOLIFY_KEY:?}"
|
|
APP_UUID=$(jq -r '.app.uuid' deploy.json) # from local deploy.json
|
|
curl -sS -H "Authorization: Bearer $COOLIFY_KEY" \
|
|
"$COOLIFY_URL/api/v1/applications/$APP_UUID/envs" \
|
|
| jq -r '.[] | select(.is_preview==false) | "\(.key)=\(.value)"'
|
|
```
|
|
|
|
If `deploy.json` is not present, list applications under the Volcanic MFEs project and find the one named `nats`:
|
|
|
|
```bash
|
|
curl -sS -H "Authorization: Bearer $COOLIFY_KEY" \
|
|
"$COOLIFY_URL/api/v1/projects/p4fts5a0kv3tahzjtbtfequk" \
|
|
| jq '.applications[] | {uuid, name}'
|
|
```
|
|
|
|
### WebSocket URL
|
|
|
|
```
|
|
wss://nats.tes.gd
|
|
```
|
|
|
|
The NATS server accepts standard NATS-over-WebSocket framing (RFC 6455 with the `nats` subprotocol). No custom path; connect to the root URL.
|
|
|
|
### With `nats` CLI
|
|
|
|
```bash
|
|
nats \
|
|
--server=wss://nats.tes.gd \
|
|
--user="$NATS_USER" --password="$NATS_PASSWORD" \
|
|
server info
|
|
```
|
|
|
|
### With `nats.js` / `nats.ws` (Node/browser)
|
|
|
|
```js
|
|
import { connect } from 'nats.ws'; // browser
|
|
// import { connect } from 'nats'; // node with ws
|
|
|
|
const nc = await connect({
|
|
servers: 'wss://nats.tes.gd',
|
|
user: process.env.NATS_USER,
|
|
pass: process.env.NATS_PASSWORD,
|
|
});
|
|
```
|
|
|
|
### With `nats-py`
|
|
|
|
```python
|
|
import asyncio, os
|
|
from nats.aio.client import Client as NATS
|
|
|
|
async def main():
|
|
nc = NATS()
|
|
await nc.connect(
|
|
servers=['wss://nats.tes.gd'],
|
|
user=os.environ['NATS_USER'],
|
|
password=os.environ['NATS_PASSWORD'],
|
|
)
|
|
await nc.publish('hello', b'world')
|
|
await nc.drain()
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
## What's inside the server
|
|
|
|
- **Listeners**
|
|
- `4222` — native NATS protocol, `expose`d only inside the compose network. Not reachable from outside.
|
|
- `8080` — WebSocket listener, `no_tls: true`. Traefik terminates TLS and forwards `ws://nats:8080` from the public `wss://nats.tes.gd`.
|
|
- `8222` — HTTP monitoring (`/healthz`, `/varz`, `/jsz`), internal only. Used by the compose healthcheck.
|
|
- **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.
|
|
|
|
## Managing / redeploying
|
|
|
|
Config or compose changes → commit and push to `main`, then trigger a Coolify deploy (fire-and-forget):
|
|
|
|
```bash
|
|
: "${COOLIFY_URL:?}" "${COOLIFY_KEY:?}"
|
|
APP_UUID=$(jq -r '.app.uuid' deploy.json) # or look it up as shown above
|
|
curl -sS -X POST "$COOLIFY_URL/api/v1/deploy?uuid=$APP_UUID" \
|
|
-H "Authorization: Bearer $COOLIFY_KEY"
|
|
# → { "deployments": [ { "deployment_uuid": "…" } ] } done, don't poll
|
|
```
|
|
|
|
Rotating the password: PATCH the `NATS_PASSWORD` env on the Coolify app, then redeploy. The value is substituted into `configs.nats-conf.content` at compose parse time.
|
|
|
|
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.
|
|
|
|
## Files in this repo
|
|
|
|
| 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. |
|
|
| `deploy.json` (local only) | Coolify app config used by the `deploying-to-coolify-via-api` skill. |
|