NATS JetStream Console

A modern, enterprise-grade web console for managing NATS JetStream clusters. Built with Next.js, Node.js, and TypeScript, featuring real-time monitoring and a developer-friendly experience.

Maintained by KLogic

Features

• Multi-cluster Management - Connect and manage multiple NATS JetStream clusters
• Stream Management - Create, configure, and monitor streams with message browser
• Consumer Management - Manage consumers with real-time lag visualization
• Real-time Metrics - Live dashboards with ClickHouse-backed analytics
• Alerting - Configurable alerts for lag, throughput, and errors
• Team Collaboration - Multi-tenant with organizations and teams

Tech Stack

Layer	Technology
Frontend	Next.js 15, React 19, TypeScript, TailwindCSS, shadcn/ui, TanStack Query
Backend	Fastify, Prisma ORM, PostgreSQL
Metrics	ClickHouse (time-series), Redis (cache/sessions)
Messaging	NATS JetStream

---

Deployment Options

Choose the deployment method that fits your needs:

Method	Use Case	Complexity
All-in-One Docker	Quick demos, testing, local dev	Simple
Docker Compose (All-in-One)	Easy deployment with volume persistence	Simple
Docker Compose (Production)	Production deployments	Medium
Local Development	Active development with hot reload	Medium

---

1. All-in-One Docker Image

The simplest way to try NATS Console. A single container with all services embedded.

Quick Start

# Build the image
docker build -t nats-console:allinone .

# Run the container
docker run -d \
  --name nats-console \
  -p 3000:3000 \
  -p 3001:3001 \
  -p 4222:4222 \
  -p 8222:8222 \
  -e JWT_SECRET="your-secret-key-change-in-production" \
  nats-console:allinone

Access

Service	URL
Web Dashboard	http://localhost:3000
API	http://localhost:3001
NATS Client	nats://localhost:4222
NATS Monitoring	http://localhost:8222

With Data Persistence

docker run -d \
  --name nats-console \
  -p 3000:3000 \
  -p 3001:3001 \
  -p 4222:4222 \
  -v nats-console-postgres:/var/lib/postgresql/data \
  -v nats-console-redis:/var/lib/redis \
  -v nats-console-clickhouse:/var/lib/clickhouse \
  -v nats-console-nats:/var/lib/nats \
  -e JWT_SECRET="your-secret-key-change-in-production" \
  nats-console:allinone

---

2. Docker Compose (All-in-One)

Same all-in-one container but managed with Docker Compose for easier configuration.

# Start
docker-compose -f docker-compose.allinone.yml up -d

# View logs
docker-compose -f docker-compose.allinone.yml logs -f

# Stop
docker-compose -f docker-compose.allinone.yml down

# Stop and remove data
docker-compose -f docker-compose.allinone.yml down -v

Custom Configuration

Create a .env file:

cp .env.example .env
# Edit .env with your settings

JWT_SECRET=your-secure-random-string-here
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

---

3. Docker Compose (Production)

For production deployments with separate, scalable services.

Prerequisites

• Docker & Docker Compose
• At least 4GB RAM recommended

Setup

1. Create environment file

cp .env.example .env.prod

2. Edit production environment (.env.prod)

NODE_ENV=production

# Database
DATABASE_URL=postgresql://nats_console:secure_password@postgres:5432/nats_console
POSTGRES_PASSWORD=secure_password

# Redis
REDIS_URL=redis://redis:6379

# ClickHouse
CLICKHOUSE_URL=http://clickhouse:8123
CLICKHOUSE_DATABASE=nats_console

# NATS
NATS_URL=nats://nats:4222

# Security (IMPORTANT: Use a secure random string!)
JWT_SECRET=generate-with-openssl-rand-hex-32
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

3. Start services

# Build and start
docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d

# Run database migrations
docker-compose -f docker-compose.prod.yml exec api npx prisma migrate deploy

# Check status
docker-compose -f docker-compose.prod.yml ps

# View logs
docker-compose -f docker-compose.prod.yml logs -f

With Nginx Reverse Proxy

# Include nginx profile
docker-compose -f docker-compose.prod.yml --profile with-nginx up -d

Scaling

# Scale API instances
docker-compose -f docker-compose.prod.yml up -d --scale api=3

# Scale workers
docker-compose -f docker-compose.prod.yml up -d --scale workers=2

---

4. Local Development Mode

For active development with hot reload. Infrastructure runs in Docker, apps run locally.

Prerequisites

• Node.js 20+
• pnpm 9+
• Docker & Docker Compose

Setup

1. Clone and install

git clone https://github.com/your-org/nats-console.git
cd nats-console
pnpm install

2. Start infrastructure services

# Start PostgreSQL, Redis, ClickHouse, NATS
docker-compose -f docker-compose.dev.yml up -d

# Or use the existing docker-compose.yml
docker-compose up -d

3. Setup environment

# Copy environment files
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
cp apps/workers/.env.example apps/workers/.env

4. Initialize database

# Generate Prisma client
make prisma-generate

# Run migrations
make prisma-migrate

5. Start development servers

# Start all services with hot reload
make dev

# Or start individually
make api-dev    # API only
make web-dev    # Web only
make workers-dev # Workers only

Access

Service	URL
Web Dashboard	http://localhost:3000
API	http://localhost:3001
NATS Monitoring	http://localhost:8222
Prisma Studio	make prisma-studio

One-Command Setup

make setup && make dev

---

Makefile Commands

Development

make dev              # Start all services in dev mode
make api-dev          # Start API only
make web-dev          # Start Web only
make workers-dev      # Start Workers only

Database Operations

make db-up            # Start database containers
make db-down          # Stop database containers
make db-shell-postgres  # PostgreSQL shell
make db-shell-redis     # Redis CLI
make db-shell-clickhouse # ClickHouse client
make db-shell-nats      # NATS CLI

Prisma

make prisma-generate  # Generate Prisma client
make prisma-migrate   # Run migrations
make prisma-studio    # Open Prisma Studio
make prisma-reset     # Reset database

Build & Production

make build            # Build all packages
make start            # Start in production mode
make health           # Check health of all services

Docker

make docker-build-allinone  # Build all-in-one image
make docker-up-allinone     # Start all-in-one container
make docker-down            # Stop all containers

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          Browser                                │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                        ┌─────▼─────┐
                        │  Web UI   │
                        │ (Next.js) │
                        └─────┬─────┘
                              │ HTTP/REST
                              │
                        ┌─────▼─────┐
                        │    API    │◄─────────────────────────────┐
                        │ (Fastify) │                              │
                        └─────┬─────┘                              │
                              │                                    │
          ┌───────────────────┼───────────────────┐                │
          │                   │                   │                │
    ┌─────▼─────┐       ┌─────▼─────┐       ┌─────▼─────┐    ┌─────▼──────┐
    │ PostgreSQL│       │   Redis   │       │ ClickHouse│    │  Workers   │
    │   (Data)  │       │  (Cache)  │       │ (Metrics) │    │(Background)│
    └───────────┘       └───────────┘       └───────────┘    └─────┬──────┘
                                                                   │
          ┌────────────────────────────────────────────────────────┘
          │
          │  ┌─────────────────────────────────────────────────────┐
          │  │          NATS JetStream Clusters                    │
          │  │  (Managed by API - streams, consumers, messages)    │
          └──►                                                     │
             └─────────────────────────────────────────────────────┘

Data Flow:

• Web UI → API: All frontend requests go through the REST API
• API → NATS: API connects to NATS clusters to manage streams/consumers
• Workers → NATS: Background jobs for metrics collection and alerting

---

Testing with Example Apps

The examples/ directory contains sample NATS applications:

cd examples

# Install dependencies
pnpm install

# Setup example streams
pnpm run setup-streams

# Run message producer
pnpm run producer

# Run message consumer
pnpm run consumer

# Run high-volume load test
pnpm run load-test

---

Environment Variables

Variable	Description	Default
NODE_ENV	Environment mode	development
PORT	API server port	3001
DATABASE_URL	PostgreSQL connection string	-
REDIS_URL	Redis connection string	-
CLICKHOUSE_URL	ClickHouse HTTP URL	-
NATS_URL	NATS server URL	-
JWT_SECRET	JWT signing secret	-
JWT_EXPIRES_IN	Access token expiry	15m
JWT_REFRESH_EXPIRES_IN	Refresh token expiry	7d

See .env.example for the complete list.

---

Troubleshooting

Container won't start

# Check logs
docker logs nats-console

# Check if ports are in use
lsof -i :3000,:3001,:4222

# Restart with fresh data
docker-compose down -v
docker-compose up -d

Database connection issues

# Check PostgreSQL is running
docker exec nats-console-postgres pg_isready

# Check Redis
docker exec nats-console-redis redis-cli ping

# Check ClickHouse
curl http://localhost:8123/ping

Reset everything

# Stop all containers and remove volumes
docker-compose down -v

# Remove images
docker rmi nats-console:allinone

# Start fresh
docker-compose up -d --build

---

Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/my-feature
3. Commit changes: git commit -am 'Add feature'
4. Push to branch: git push origin feature/my-feature
5. Open a Pull Request

---

License

MIT License - see LICENSE for details.