NATS Server
The NATS server is the central communication point for PUDA. The CLI, edge services, and logger services all depend on it for commands, telemetry, events, and logs.
v0.1.0 uses one of two layouts from infra/nats in the PUDA repository:
- Single-node — one NATS server on one always-on computer. No failover.
- Three-node — one NATS server on each of three computers on the same network (LAN or Tailscale). The cluster survives one host going down.
After the server is running, apply the JetStream streams and KV buckets once from infra/nats/jetstream. Do not skip that step.
Use a mini PC, Raspberry Pi, or another small always-on machine. Install a stable Linux distribution such as Ubuntu Server or Debian.
Install Docker
Install Docker Engine by following the official Docker instructions for your Linux distribution:
After Docker is installed, confirm that Docker Compose is available:
docker compose version
Clone the PUDA repository so you have the NATS layouts and JetStream configs:
git clone https://github.com/PUDAP/puda.git
cd puda/infra/nats
Single-node
One computer runs the NATS server. Follow single-node/README.md.
cd single-node
cp .env.example .env
Set HOST_IP in .env to this computer's reachable LAN or Tailscale address. Then:
docker compose up -d
Apply JetStream with one replica:
cd ../jetstream
NATS_URL=nats://localhost:<port> REPLICAS=1 ./setup_streams.sh
The NATS client URL is:
nats://<nats-server-host>:<port>
This layout has no server or JetStream failover.
Three-node
Use three computers on the same network. Copy three-node-r3/nats1/, nats2/, and nats3/ to one host each. Follow three-node-r3/README.md.
The PUDAP/puda-nats-template repository is the same three-computer layout (machine1, machine2, machine3).
On each host:
cp .env.example .env
Fill in reachable addresses for this host and the other two. Route port 6222 must be reachable between all three computers. Then on every host:
docker compose up -d
After all three nodes are up, apply JetStream once from an operator machine that has infra/nats/jetstream:
cd jetstream
NATS_URL=nats://<nats1-host>:<port> REPLICAS=3 ./setup_streams.sh
Do not run the JetStream bootstrap independently on all three servers.
Configure PUDA clients with all three URLs:
NATS_SERVERS=nats://<nats1-host>:<port>,nats://<nats2-host>:<port>,nats://<nats3-host>:<port>
Once this is done, you can start integrating a new machine.
Optional: sync host clocks with Clock Sync so timestamps agree across the NATS host and every edge.