Skip to main content

Source: docs/manual/debian-deploy.md

This page is generated by site/scripts/sync-manual-docs.mjs.

Debian Deployment Guide

NATS Event Bus (Phase 12)​

Installation​

# Install NATS server
curl -L https://github.com/nats-io/nats-server/releases/download/v2.10.x/nats-server-v2.10.x-linux-amd64.tar.gz | tar xz
sudo cp nats-server /usr/local/bin/
sudo useradd --system --home /var/lib/nats --shell /usr/sbin/nologin nats || true
sudo mkdir -p /var/lib/nats
sudo chown -R nats:nats /var/lib/nats

Systemd Unit​

Create /etc/systemd/system/nats.service:

[Unit]
Description=NATS Server
After=network.target

[Service]
Type=simple
User=nats
ExecStart=/usr/local/bin/nats-server --jetstream --store_dir /var/lib/nats --max_mem 128M -m 8222
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now nats
sudo systemctl status nats

Memory Budget​

  • NATS server: 64-128MB (configured by --max_mem)
  • JetStream: use file store (--store_dir) to keep memory usage bounded
  • Total incremental runtime footprint: about 128MB on an 8GB target host

Cruvero Configuration​

Set the core event-bus values:

CRUVERO_EVENTS_BACKEND=nats
CRUVERO_NATS_URL=nats://localhost:4222
CRUVERO_AUDIT_BUFFER=nats

TLS (Optional Production Hardening)​

  • Provision server certificates (internal PKI or Let's Encrypt)
  • Enable TLS in NATS with --tls --tlscert --tlskey
  • Configure clients with:
CRUVERO_NATS_TLS=auto

Monitoring​

  • NATS monitoring endpoint: http://localhost:8222
  • JetStream stats endpoint: http://localhost:8222/jsz
  • CLI health check:
event-bus status --nats-url nats://localhost:4222

Optional Components​

  • embed-worker: run as a separate systemd unit for async embedding mode
  • Audit consumer: runs in-process with cmd/worker by default