/nats-dashboard

Web dashboard for monitoring NATS servers.

Primary LanguageTypeScriptMIT LicenseMIT

NATS Web Dashboard

A web dashboard to display live NATS server monitoring metrics.

Live demo monitoring the demo NATS server at https://demo.nats.io:8222.

About

This is a static web app that was inspired by nats-top, it fetches and displays the monitoring stats of a NATS server but in the browser instead of the CLI.

Since this is a static web app, it can be deployed anywhere and can also run locally on your machine.

This is also a PWA (Progressive Web App) so it's installable and usable offline, but of course you need access to the NATS server, for example you can monitor a local NATS server while being offline.

There's no backend involved, the requests are made directly from the browser, so you can monitor a local NATS server (http://localhost:8222) even when the app is not running locally.

There's no data retention, so no historical stats can be displayed, you will only be able to view the live server stats, if you need this feature you should use a Prometheus exporter with Grafana and set an appropriate data retention policy.

Using the App

PWA

The app is deployed on Cloudflare Pages at:

https://natsdashboard.com

The app can be installed on your device for offline use (Desktop or mobile).

Docker Image

docker run --rm -it -p 8000:80 mdawar/nats-dashboard

The image uses Caddy server and exposes port 80.

In the example above we map the image port 80 to port 8000 on localhost.

Development

Requirements

  • Node: Version defined in .nvmrc file (If you have nvm installed, run nvm use)
  • Docker + Compose Plugin (Optional): Used for running a local NATS server and the app preview

Install the required packages:

npm i

Run the web app in dev mode

npm start

Run a local NATS server

# Start a local NATS server using Docker compose
make server
# Remove containers and volumes
make clean

Run the tests

There are a few tests for a couple of functions for now, more tests will be added later.

npm test
# Run the tests and watch for changes
npm run test:watch

Build the App

Build the Web App

# Build a static web app to ./dist
npm run build

To build a sitemap and to have proper URL meta tags, the SITE_DOMAIN environment variable must be set.

# The SITE_DOMAIN env variable sets the Astro.site config.
SITE_DOMAIN=https://example.com npm run build

Build Docker Image

Build using Docker compose:

make build
# Or
docker compose build

The SITE_DOMAIN environment variable will be passed as a build argument if set.

Or using the Docker CLI:

docker build -t nats-dashboard .
# The site domain can be passed as a build arg.
docker build -t nats-dashboard --build-arg SITE_DOMAIN=https://example.com .

Build and Preview

Build the Docker image and run the server on http://localhost:8000 with a NATS server running on port 4222.

This is useful for testing SSG and the PWA config (eg: service worker).

make preview
# Or
docker compose build && docker compose up

The SITE_DOMAIN environment variable will be passed as a build argument if set.

Cleanup:

# Remove containers and volumes
make clean
# Or
docker compose down -v

Data Fetching

By default the data is fetched using the Fetch API since NATS server started supporting CORS in v2.9.22.

For NATS servers < v2.9.22 there's an option to use JSONP requests that fetch the data by injecting a <script> tag that executes and calls a JavaScript function that receives the data.

This option must be explicitly enabled in the app settings.

Service Worker

The service worker is generated after the site is built, it's available at src/sw.ts, it's built by vite using the script scripts/build-sw.mjs and then the Workbox precache manifest is injected by the scripts/workbox.mjs script.

The service worker is registered only in production mode by the script src/register-sw.ts that's imported by the base layout at src/layouts/Base.astro.

To test locally, use make preview to build the Docker container and run a Caddy server similar to a production environment.

Generate the Service Worker

# This is automatically run after the build script.
npm run generateSW

GitHub Actions Requirements

Repository Variables

Variable Name Description
DOCKERHUB_USER Required to push the Docker image to Docker Hub.
SITE_DOMAIN Needed to generate a sitemap and the URL meta tags (Optional).

Repository Secrets

Secret Name Description
CLOUDFLARE_ACCOUNT_ID Required for uploading the assets to Cloudflare Pages.
CLOUDFLARE_ZONE_ID Required for purging the zone cache.
CLOUDFLARE_API_TOKEN Required for Clouflare Pages and for purging the zone cache.
DOCKERHUB_TOKEN Required to push the Docker image to Docker Hub.

Required Permissions

  • Cloudflare API Token with the following permissions:

    • Account > Cloudflare Pages > Edit
    • Zone > Cache Purge > Purge

  • Docker Hub token with Read, write, delete scope.

Alternatives

Credits