NATS Server

The NATS server is the central communication point for PUDA. It should run on a machine that stays powered on, because the PUDA CLI, edge services, and logger services all depend on it for commands, telemetry, events, and logs.

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:

Install Docker Engine

After Docker is installed, confirm that Docker Compose is available:

docker compose version

Single NATS server

For a small PUDA setup, a single NATS server is enough. Create a project directory on the NATS machine:

mkdir puda-nats
cd puda-nats

Create compose.yml:

compose.yml

services:
  nats:
    image: nats:2.12.2
    container_name: nats
    restart: always
    network_mode: host
    ports:
      - "4222:4222"
      - "8222:8222"
      - "1883:1883"
    volumes:
      - nats:/data
      - ./nats.conf:/etc/nats/nats.conf:ro
    command: "-c /etc/nats/nats.conf"

volumes:
  nats:

Create nats.conf:

nats.conf

# Client connection port
port: 4222

# HTTP monitoring port
http_port: 8222

# mqtt config
mqtt {
  port: 1883
}

# Max payload size for messages
max_payload: 64MB

# JETSTREAM CONFIGURATION
# https://docs.nats.io/running-a-nats-service/configuration/resource_management
jetstream {
    store_dir: "/data/jetstream"
    max_mem: 4G
    max_file: 10G

    request_queue_limit: 1000
    limits {
      max_ha_assets = 2000
    }
}

Start the server:

docker compose up -d

The NATS client URL is:

nats://<nats-server-ip>:4222

Use the Tailscale IP or hostname if you followed the recommended network setup.

NATS cluster

For a more resilient PUDA setup, run a NATS cluster instead of a single server. A cluster lets multiple NATS servers work together as one communication layer, so PUDA clients can keep operating even if one server or machine goes offline.

A NATS cluster is useful when you want:

• Higher availability — clients can connect to another NATS server if one node is unavailable.
• JetStream quorum — persisted streams and key-value state can be replicated across nodes.
• Maintenance without full downtime — one server can be restarted while the rest of the cluster continues serving clients.
• Better lab resilience — if the NATS server runs on small hardware such as mini PCs or Raspberry Pis, a cluster reduces the impact of one device failing.

The recommended PUDA cluster shape is three NATS servers connected through NATS routes:

Node	Client port	Route port	Role
nats1	4222	6222	Accepts PUDA client connections and participates in the cluster.
nats2	4222	6222	Accepts PUDA client connections and participates in the cluster.
nats3	4222	6222	Accepts PUDA client connections and participates in the cluster.

Configure PUDA clients with all three servers so they can reconnect automatically if one node is unavailable:

.env

NATS_SERVERS=nats://nats1:4222,nats://nats2:4222,nats://nats3:4222

Use the PUDAP/puda-nats-template repository to set up the cluster and follow the instructions in its README. The template contains the Docker Compose and NATS configuration needed for the recommended setup.

Once this is done, you can start integrating a new machine.