NATS Server — Setup & Architecture

NATS 2.10 JetStream server for the Fossil NATS Sync project. Provides durable pub/sub messaging between Fossil repositories and their leaf-node agents.

Public endpoint: tls://sync.craftdesign.group:4222

---

Architecture

/*    9 */  arrow from 1st box.e right 0.3 then right 0.9; "TLS :4222" above
/*   10 */  arrow from 2nd box.e right 0.3 then right 0.9; "TLS :4222" above
/*   11 */  arrow from 3rd box.e right 0.3 then right 0.9; "TLS :4222" above
/*   12 */  
/*   13 */  # NATS server box
/*   14 */  NX = 2.8
               ^
ERROR: syntax error

---

What Is Installed

Component	Version	Path
nats-server	2.10.22	/usr/local/bin/nats-server
nats CLI	0.1.4	/usr/local/bin/nats
nsc	2.9.0	~/.local/bin/nsc (dmestas)
acme.sh	latest	/root/.acme.sh/acme.sh
TLS cert	Let's Encrypt ECC	/var/nats/tls/sync.craftdesign.group.{crt,key}

Key Paths

Path	Purpose
/usr/local/bin/nats-server	Server binary
/etc/nats/nats-server.conf	Live rendered config
/etc/nats/nats-server.conf.template	Config template (envsubst vars)
/etc/nats/operator.env	Operator JWT (root-owned, 0600)
/etc/nats/cf-token.env	Cloudflare API token (root-owned, 0600)
/var/nats/jetstream/	JetStream message storage
/var/nats/jwt/	Account JWT resolver directory
/var/nats/tls/	TLS cert + key
~/Projects/infra/nats/creds/	.creds files for each user
~/.local/share/nats/nsc/	nsc operator/account/key store (dmestas)
/etc/systemd/system/nats.service	Systemd unit

---

Auth Hierarchy

/*    1 */  scale = 0.8
/*    2 */  
/*    3 */  # Operator
/*    4 */  box "Operator: fossil-sync" wid 3.2 ht 0.5 rad 6px at (2.5, 3.0) fill lightyellow bold
                                                                                              ^^^^
ERROR: syntax error

• admin users: full > pub/sub (local provisioning only)
• bridge users: scoped to fossil.<account>.> (bridge daemon)
• SYS account: NATS system events (server-internal use)

---

JetStream Streams

Stream	Subject filter	Retention	Max size
EDGESYNC	fossil.edgesync.>	7 days	1 GB
GO_LIBFOSSIL	fossil.go-libfossil.>	7 days	1 GB

Storage: file (/var/nats/jetstream/) Replicas: 1 (single-node) Discard policy: old (drop oldest when full) Dupe window: 2 minutes

---

Install Scripts (4 Phases)

All scripts live in nats/ in the infra Fossil repo.

/*    1 */  scale = 0.85
/*    2 */  X = 0.0
              ^
ERROR: syntax error

Running a fresh install

# On the server, as dmestas:
cd ~/Projects/infra

# Phase 1 (root) — idempotent
export NATS_VERSION=2.10.22
sudo --preserve-env=NATS_VERSION bash nats/install.sh

# Phase 2 (dmestas) — idempotent
bash nats/bootstrap-creds.sh

# Phase 3 (root) — idempotent
sudo bash nats/start.sh

# Phase 4 (dmestas)
bash nats/provision-streams.sh

Prerequisites for Phase 1:

• /etc/nats/cf-token.env must exist with CF_Token="<token>" and mode 0600

Prerequisites for Phase 2:

• nsc installed (~/.local/bin/nsc)
• Phase 1 complete

---

Firewall

UFW is used (not Hetzner Cloud firewall).

sudo ufw allow 4222/tcp   # NATS TLS (already open)
sudo ufw status

Port 4222 is the only NATS-related port that needs to be open externally.