DEV Community

Cover image for Self-hosting NATS on Dokploy in under 10 minutes
Huy Pham
Huy Pham

Posted on

Self-hosting NATS on Dokploy in under 10 minutes

#docker #tutorial #showdev #devops

You picked Dokploy because you wanted Heroku-flavored ergonomics on your own VPS. Then you needed a message bus — pub/sub, JetStream persistence, maybe a WebSocket endpoint for the browser — and suddenly you're back in the YAML mines: writing a nats.conf, figuring out where the token lives, working out why Traefik won't terminate TLS in front of a raw TCP port, and wondering whether /varz is safe to expose to the internet (spoiler: it isn't).

I hit every one of those and packaged the fix as a single Dokploy Compose service: quochuydev/dokploy-nats. This post is the walkthrough I wish I'd had.

What you get

One docker-compose.yml that gives you:

  • NATS core on 4222 for in-cluster apps
  • JetStream with file-backed persistence (durable streams, KV, object store)
  • WebSocket on 8080, ready to put behind Traefik as wss://
  • HTTP monitoring on 8222 — /healthz, /varz, /connz, /jsz
  • Token auth wired through env vars, no plaintext in the repo

It's deliberately boring. No operator JWT, no clustering, no leaf nodes — just the smallest thing that's actually useful for a side project or a small team.

Step 1 — Create the Compose service

In Dokploy: Create Service → Compose, point it at the repo (or your fork), branch main, compose path docker-compose.yml. That's the entire "deploy" step.

Step 2 — Set a real token

The one thing you must not skip. In the Environment tab paste .env.example and replace the token:

openssl rand -hex 32
Enter fullscreen mode Exit fullscreen mode

Drop the output into NATS_AUTH_TOKEN. The container reads nats.conf which references $NATS_AUTH_TOKEN — no rebuild needed, just redeploy.

Step 3 — Expose the two HTTP-shaped ports

Traefik routes HTTP(S), not raw TCP, so the two ports you can publish over your domain are the monitoring endpoint and the WebSocket endpoint:

Host Service Container Port
nats-monitor.<your-domain> nats 8222
nats-ws.<your-domain> nats 8080

Add both in the service's Domains tab. Dokploy will provision certs.

Step 4 — Lock down /varz

This is the step everyone forgets. The monitoring endpoint cheerfully tells the world your subjects, connected clients, JetStream sizes, and server version. You want basic auth in front of it.

Generate a hashed credential:

htpasswd -nb admin 'a-real-password'
Enter fullscreen mode Exit fullscreen mode

Open Dokploy → Settings → Traefik and add to middlewares.yml:

http:
  middlewares:
    nats-monitor-auth:
      basicAuth:
        users:
          - "admin:$apr1$G3T3XOqn$6JGifVcvveyWFg7gYWZjH0"
Enter fullscreen mode Exit fullscreen mode

Then attach nats-monitor-auth@file to the nats-monitor row in Domains. Done — /varz now prompts for credentials.

Step 5 — Talk to it

Install the NATS CLI and save a context pointing at your WebSocket URL:

nats context save dokploy \
  --server wss://nats-ws.<your-domain> \
  --token "$NATS_AUTH_TOKEN" \
  --select

nats sub demo &
nats pub demo "hello from dokploy"
Enter fullscreen mode Exit fullscreen mode

For JetStream:

nats stream add events --subjects "events.*" --storage file --defaults
nats pub events.user.signup '{"id":"u1"}'
nats stream view events
Enter fullscreen mode Exit fullscreen mode

If you want to see this from an actual app, examples/node has a Fastify UI plus a worker showing request/reply, live WebSocket events, and prefix-scoped subscriptions.

The 4222 question

Traefik can't proxy the native protocol. If you need apps outside the Dokploy host to use port 4222 directly, you have two options:

  1. Add ports: ["4222:4222"] to the nats service and open the firewall (and seriously consider TLS — see "Extending" in the README).
  2. Use the WebSocket endpoint from any client that supports it — every official NATS client does.

For most setups, option 2 is the right answer. Browser clients get the same endpoint as your services, and you only have one thing to secure.

When to outgrow this setup

This repo is intentionally a starting point. The moment you need any of:

  • TLS/mTLS between services — add a tls { ... } block to nats.conf
  • Clustering or leaf nodes — cluster { ... } / leafnodes { ... } blocks
  • Per-account isolation or JWT auth — swap the authorization block for accounts + operator JWT
  • KV or Object store — already enabled by JetStream, just nats kv add after deploy

…edit nats.conf or docker-compose.yml, push, redeploy. Nothing magic.

Wrap-up

Five steps, one token, two domains, one Traefik middleware. You now have a durable, browser-reachable, password-protected NATS server running next to your other Dokploy apps for the cost of the disk space JetStream uses.

If you spin it up, I'd love to hear what broke. Issues and PRs welcome: github.com/quochuydev/dokploy-nats.

Top comments (0)