monitor
Real-time monitoring, slowlog analysis, and audit trails for Valkey and Redis
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/BetterDB-inc/monitor with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/BetterDB-inc/monitor'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/betterdb-inc--monitor)HTML
<a href="/listings/betterdb-inc--monitor"><img src="/api/listings/betterdb-inc--monitor/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
docker run -d --name betterdb -p 3001:3001 betterdb/monitor:latest
Point your browser to `http://localhost:3001`. To monitor a specific instance:
docker run -d \ --name betterdb \ -p 3001:3001 \ -e DB_HOST=your-valkey-host \ -e DB_PORT=6379 \ -e DB_PASSWORD=your-password \ betterdb/monitor:latest
> **Connecting to a database on your host machine?** Inside the container > `localhost` is the container itself, not your host — so use > `host.docker.internal` as the database host. On **Docker Desktop > (macOS/Windows)** it works out of the box; on **Linux** add > `--add-host=host.docker.internal:host-gateway` to the `docker run` command so > the name resolves. The dashboard's one-click "connect to local instance" > button auto-detects this and pre-fills the right host for you.
Two image variants are published, both multi-arch (`linux/amd64`, `linux/arm64`):
| Tag | What it is | |-----|------------| | `latest`, `X.Y.Z-no-ai` | Default image - every monitoring feature included, without the dependencies for the experimental local-LLM AI Helper | | `X.Y.Z` | Adds the experimental AI Helper (bring your own Ollama; disabled by default via `AI_ENABLED`) |
See [Docker Production Deployment](#docker-production-deployment) for persistent storage, custom ports, licensing, and air-gapped setups.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 26 lines
- {
- "name": "betterdb",
- "description": "BetterDB plugins for Claude Code",
- "owner": {
- "name": "BetterDB Inc.",
- "url": "https://betterdb.com"
- },
- "plugins": [
- {
- "name": "betterdb",
- "source": {
- "source": "git-subdir",
- "url": "https://github.com/BetterDB-inc/monitor.git",
- "path": "packages/mcp/claude-plugin",
- "ref": "master"
- },
- "description": "Valkey and Redis observability from BetterDB Monitor",
- "category": "monitoring",
- "tags": [
- "valkey",
- "redis",
- "observability"
- ]
- }
- ]
- }
README.md · README · 439 lines
- # BetterDB Monitor
- [](https://hub.docker.com/r/betterdb/monitor)
- [](https://hub.docker.com/r/betterdb/monitor/tags)
- [](https://artifacthub.io/packages/search?repo=betterdb-monitor)
- [](https://www.npmjs.com/package/@betterdb/monitor)
- [](https://www.npmjs.com/package/@betterdb/monitor)
- [](https://github.com/betterdb-inc/monitor/actions/workflows/api-tests.yml)
- [](LICENSE)
- [](https://valkey.io)
- [](https://redis.io)
- **The monitoring layer that Valkey deserves.**
- BetterDB persists what Valkey throws away - slowlogs, command patterns, client activity, anomaly signals - so you can debug what happened at 3am, not just what's happening now. Built for Valkey 8.x with native support for COMMANDLOG, CLUSTER SLOT-STATS, and per-thread I/O metrics. Redis 6+ compatible for everything else.
- [Website](https://betterdb.com) | [Docker Hub](https://hub.docker.com/r/betterdb/monitor) | [npm](https://www.npmjs.com/package/@betterdb/monitor) | [Documentation](https://docs.betterdb.com) | [Blog](https://betterdb.com/blog)
- BetterDB is built by [BetterDB Inc.](https://betterdb.com), a public benefit company operating under the [OCV Open Charter](https://github.com/OpenCoreVentures/ocv-public-benefit-company).
- 
- ## Quick Start (Docker)
- ```bash
- docker run -d --name betterdb -p 3001:3001 betterdb/monitor:latest
- ```
- Point your browser to `http://localhost:3001`. To monitor a specific instance:
- ```bash
- docker run -d \
- --name betterdb \
- -p 3001:3001 \
- -e DB_HOST=your-valkey-host \
- -e DB_PORT=6379 \
- -e DB_PASSWORD=your-password \
- betterdb/monitor:latest
- ```
- > **Connecting to a database on your host machine?** Inside the container
- > `localhost` is the container itself, not your host — so use
- > `host.docker.internal` as the database host. On **Docker Desktop
- > (macOS/Windows)** it works out of the box; on **Linux** add
- > `--add-host=host.docker.internal:host-gateway` to the `docker run` command so
- > the name resolves. The dashboard's one-click "connect to local instance"
- > button auto-detects this and pre-fills the right host for you.
- Two image variants are published, both multi-arch (`linux/amd64`, `linux/arm64`):
- | Tag | What it is |
- |-----|------------|
- | `latest`, `X.Y.Z-no-ai` | Default image - every monitoring feature included, without the dependencies for the experimental local-LLM AI Helper |
- | `X.Y.Z` | Adds the experimental AI Helper (bring your own Ollama; disabled by default via `AI_ENABLED`) |
- See [Docker Production Deployment](#docker-production-deployment) for persistent storage, custom ports, licensing, and air-gapped setups.
- ## Quick Start (Kubernetes / Helm)
- ```bash
- helm repo add betterdb https://docs.betterdb.com/charts
- helm repo update
- helm install betterdb-monitor betterdb/betterdb-monitor \
- --namespace betterdb --create-namespace \
- --set db.host=my-valkey.default.svc.cluster.local \
- --set db.password=yourpassword
- ```
- Then `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001` and open `http://localhost:3001`, or enable the chart's ingress. PostgreSQL-backed history, bring-your-own Secrets, and air-gapped licensing are all covered in the [Kubernetes guide](https://docs.betterdb.com/kubernetes) and the [chart README](charts/betterdb-monitor/README.md).
- ## Quick Start (CLI)
- Run BetterDB Monitor without Docker:
- ```bash
- npx @betterdb/monitor
- ```
- On first run, an interactive setup wizard guides you through database connection, storage backend (SQLite, PostgreSQL, or in-memory), and server settings. Configuration is saved to `~/.betterdb/config.json`.
- ```bash
- npm install -g @betterdb/monitor # global install
- betterdb --setup # re-run setup wizard
- betterdb --port 8080 # override server port
- betterdb --db-host 1.2.3.4 # override database host
- betterdb --help # all options
- ```
- Requires Node.js >= 20.0.0 and a Valkey or Redis instance to monitor. For SQLite storage, also `npm install -g better-sqlite3`.
- ## What You Get
- ### See everything, keep everything
- - **Historical analytics** - query slowlogs, command patterns, client activity, and latency across any time range. The data that used to disappear after a log rotation.
- - **COMMANDLOG support** - Valkey 8.1+ exclusive. Large requests and large replies, not just the slow ones.
- - **MONITOR capture sessions** - record real traffic on demand: live tail, filter, replay, export to JSON/CSV, and cross-reference against connection history.
- - **Hot key tracking** - top keys by access frequency with rank movement over time. Key Analytics (Pro, free in early access) adds type, TTL, and size distributions from live sampling.
- - **Cluster visibility** - topology graphs, SLOT-STATS heatmaps, per-slot CPU and key distribution.
- - **Cluster auto-registration** - a cluster connection can auto-register every node as its own monitored connection, kept in sync as the cluster scales. See [docs/cluster-auto-registration.md](docs/cluster-auto-registration.md).
- - **CPU & I/O thread metrics** - per-thread visibility that no Redis tool can provide.
- - **Client analytics** - see exactly which service is responsible for what, attributed by client name and pattern.
- - **ACL audit trail** - track who accessed what, persisted for compliance and post-incident debugging.
- ### Understand and act
- - **Anomaly detection** (Pro, free in early access) - automatic baseline learning with correlated events and plain-English diagnoses. 20+ detectors, no manual thresholds.
- - **Capacity forecasting** - projected time-to-ceiling for memory, ops/sec, CPU, and fragmentation.
- - **Webhooks** - HMAC-signed alert deliveries with retries and a full delivery log.
- - **Live migration** - move between Redis and Valkey, self-hosted or managed (ElastiCache node-based or Serverless, MemoryDB, Redis Cloud, Upstash), standalone or cluster (a cluster source needs a cluster target). Three-phase analysis, execution, and validation workflow, with PSYNC-based continuous replication for near-zero-downtime cutovers when the source permits replication commands. Other RESP-compatible engines such as KeyDB and Dragonfly work in the modes listed in the [engine table](docs/migration.md#other-engines); they are not part of the test suite. See [docs/migration.md](docs/migration.md).
- ### Built for the AI era
- - **Vector search observability** - FT.SEARCH ops/sec and latency with per-index health for [valkey-search](https://github.com/valkey-io/valkey-search) and RediSearch. See [docs/vector-ai](docs/vector-ai/README.md).
- - **Inference latency** - p50/p95/p99 per index, with SLA breach alerts (Pro, free in early access).
- - **Semantic cache intelligence** (Pro, free in early access) - hit-rate health, similarity-threshold recommendations, and an approve/reject proposal workflow. Agent memory observability included.
- - **AI traces** - OTLP span waterfalls from your AI application, correlated with the live Valkey state underneath each request. See [docs/opentelemetry.md](docs/opentelemetry.md).
- ### Plugs into everything
- - **MCP server** - 60 tools for Claude Code, Cursor, or any MCP client via [`@betterdb/mcp`](packages/mcp).
- - **Prometheus endpoint** - 100+ `betterdb_*` metrics. See [docs/prometheus-metrics.md](docs/prometheus-metrics.md).
- - **OpenTelemetry** - ingest OTLP traces, and mirror metrics and events to any OTLP backend. See [docs/opentelemetry.md](docs/opentelemetry.md).
- - **REST API** - everything in the UI is an API call, documented via OpenAPI.
- ## Access Your Data Your Way
- | Interface | Details |
- |-----------|---------|
- | Web UI | `http://localhost:3001` |
- | MCP server | `npx -y @betterdb/mcp@1.6.0` (stdio) - create a token under Settings → MCP Tokens (required on cloud, optional on self-hosted) |
- | Prometheus | `http://localhost:3001/api/prometheus/metrics` |
- | REST API (OpenAPI) | `http://localhost:3001/docs` |
- | Health check | `http://localhost:3001/api/health` |
- > **Note**: In production builds (Docker, CLI) API routes are served under the `/api` prefix. In local development (`pnpm dev`) there is no prefix - e.g. `http://localhost:3001/health`.
- ## Supported Databases
- | Database | Minimum Version | Supported Features |
- |----------|----------------|-------------------|
- | **Valkey** | 8.0+ | All features including COMMANDLOG (8.1+) and CLUSTER SLOT-STATS |
- | **Redis** | 6+ | All features except the Valkey-exclusive COMMANDLOG and CLUSTER SLOT-STATS |
- The backend uses a unified adapter over the wire-compatible `iovalkey` client and auto-detects Valkey vs Redis from the `INFO` response (`DB_TYPE=auto`). Capabilities like COMMANDLOG and SLOT-STATS are detected per version, and the UI gracefully degrades when a feature isn't available.
- Managed services are supported too - guides for AWS ElastiCache, MemoryDB, Redis Cloud, and Upstash live in [docs/providers](docs/providers/), and [`@betterdb/agent`](packages/agent) reaches VPC-only instances over an outbound WebSocket.
- ## Docker Production Deployment
- The Docker image contains the monitoring application (backend + frontend). It requires:
- 1. A Valkey/Redis instance to monitor
- 2. A PostgreSQL instance for data persistence (or use memory storage)
- ### Run with PostgreSQL Storage
- ```bash
- docker run -d \
- --name betterdb-monitor \
- -p 3001:3001 \
- -e DB_HOST=your-valkey-host \
- -e DB_PORT=6379 \
- -e DB_PASSWORD=your-password \
- -e STORAGE_TYPE=postgres \
- -e STORAGE_URL=postgresql://user:pass@postgres-host:5432/dbname \
- betterdb/monitor
- ```
- ### Run on Custom Port
- Set the `PORT` environment variable and match the `-p` mapping:
- ```bash
- docker run -d \
- --name betterdb-monitor \
- -p 8080:8080 \
- -e PORT=8080 \
- -e DB_HOST=your-valkey-host \
- betterdb/monitor
- ```
- ### Run with Host Network (Access localhost services)
- If your Valkey and PostgreSQL are running on the same host:
- ```bash
- docker run -d \
- --name betterdb-monitor \
- --network host \
- -e DB_HOST=localhost \
- -e DB_PORT=6380 \
- -e DB_PASSWORD=devpassword \
- -e STORAGE_TYPE=postgres \
- -e STORAGE_URL=postgresql://dev:devpass@localhost:5432/postgres \
- betterdb/monitor
- ```
- ### Environment Variables
- | Variable | Required | Default | Description |
- |----------|----------|---------|-------------|
- | `DB_HOST` | Yes | `localhost` | Valkey/Redis host to monitor |
- | `DB_PORT` | No | `6379` | Valkey/Redis port |
- | `DB_PASSWORD` | No | - | Valkey/Redis password |
- | `DB_USERNAME` | No | `default` | Valkey/Redis ACL username |
- | `DB_TYPE` | No | `auto` | Database type: `auto`, `valkey`, or `redis` |
- | `DB_TLS` | No | `false` | Set to `true` to connect to the monitored database over TLS (required by managed providers such as Aiven or ElastiCache Serverless) |
- | `DB_TLS_CA_FILE` | No | - | Path to a PEM CA bundle used to verify the database server certificate. Needed when the server certificate is issued by a private CA (see [Mutual TLS](#mutual-tls-client-certificates)) |
- | `DB_TLS_CERT_FILE` | No | - | Path to a PEM client certificate presented to the database (mutual TLS). Use together with `DB_TLS_KEY_FILE` |
- | `DB_TLS_KEY_FILE` | No | - | Path to the PEM private key matching `DB_TLS_CERT_FILE` |
- | `DB_TLS_KEY_PASSPHRASE` | No | - | Passphrase for `DB_TLS_KEY_FILE`, if the key is encrypted |
- | `DB_AUTH_MODE` | No | `password` | `password` sends `AUTH` with `DB_USERNAME`/`DB_PASSWORD`; `certificate` sends no `AUTH` so the server maps the client certificate to an ACL user (Valkey `tls-auth-clients-user`). Requires `DB_TLS=true` and a client certificate + key |
- | `STORAGE_TYPE` | No | `memory` | Storage backend: `memory` or `postgres` |
- | `STORAGE_URL` | Conditional | - | PostgreSQL connection URL (required if `STORAGE_TYPE=postgres`) |
- | `STORAGE_SSL_CA` | No | - | Path (or trusted HTTPS URL) to a CA cert used to verify the PostgreSQL server. For managed providers with their own CA (e.g. Aiven), supply the project CA here for full chain + hostname verification. Takes precedence over `STORAGE_SSL_NO_VERIFY` |
- | `STORAGE_SSL_NO_VERIFY` | No | `false` | Connect to PostgreSQL over TLS **without** verifying the server certificate (encrypted but not authenticated). Convenience for managed providers that present their own CA and force `sslmode=require` when you can't supply `STORAGE_SSL_CA`. Prefer `STORAGE_SSL_CA` in production |
- | `PORT` | No | `3001` | Application HTTP port |
- | `NODE_ENV` | No | `production` | Node environment |
- | `ANOMALY_DETECTION_ENABLED` | No | `true` | Enable anomaly detection |
- | `ANOMALY_PROMETHEUS_INTERVAL_MS` | No | `30000` | Prometheus summary update interval (ms) |
- | `BETTERDB_LICENSE_KEY` | No | - | Online license key (Pro/Enterprise), validated over the network |
- | `BETTERDB_OFFLINE_LICENSE_FILE` | No | - | Path to a signed offline license `.jwt` for **air-gapped** hosts (see below) |
- | `BETTERDB_OFFLINE_LICENSE` | No | - | Offline license token as an inline JWT string |
- | `BETTERDB_DATA_DIR` | No | `/app/data` | Directory for persisted license state (mount a writable volume) |
- | `ENCRYPTION_KEY` | No | - | Key (min 16 chars) used to envelope-encrypt stored connection passwords, TLS private keys and SSH tunnel secrets at rest. Without it, secrets are stored in plaintext; rows found in plaintext are re-encrypted on the next start once the key is set. If the key is missing while encrypted rows exist, env-configured credentials are used in memory only and never written back unencrypted |
- | `BETTERDB_SSH_KEY_DIR` | No | - | Directory that server-side SSH private keys must live in. Enables the "server file path" key source for [SSH tunnels](#ssh-tunnels); a connection's key path must resolve inside it. Unset disables file-based keys (inline pasted keys still work) |
- | `BETTERDB_TLS_CERT_DIR` | No | - | Directory that server-side TLS files (CA bundle, client certificate, key) must live in. Enables the "server file paths" source for [mutual TLS](#mutual-tls-client-certificates) on UI-added connections; a connection's paths must resolve inside it. Unset disables file paths (pasted PEM still works) |
- | `BETTERDB_TELEMETRY` | No | `true` | Set `false` to disable anonymous telemetry |
- Full reference, including AI, webhook tuning, and health-gate thresholds: [docs/configuration.md](docs/configuration.md). For OTLP trace ingest and metrics/event export, see [docs/opentelemetry.md](docs/opentelemetry.md).
- ### Mutual TLS (client certificates)
- When **Use TLS** is on, a connection can also carry TLS material:
- - a **CA bundle** so the server certificate is verified against a private PKI instead of the public CA store, and
- - a **client certificate + private key** that BetterDB presents during the handshake (mutual TLS), for servers that run `tls-auth-clients yes`.
- The certificate is passed to the TLS socket exactly as supplied, so its subject (CN) is whatever your CA issued. Material is either **pasted as PEM** (the private key and passphrase are encrypted at rest when `ENCRYPTION_KEY` is set) or referenced by **server file paths** inside `BETTERDB_TLS_CERT_DIR`, the same allowlist model as SSH keys. The env-configured default connection takes the same material from `DB_TLS_CA_FILE`, `DB_TLS_CERT_FILE`, `DB_TLS_KEY_FILE` and `DB_TLS_KEY_PASSPHRASE`.
- **Certificate-only authentication.** Valkey can map a field of the client certificate to an ACL user (`tls-auth-clients-user`). For that mapping to hold, the client must not send `AUTH` afterwards, which would re-authenticate the session as a different user or fail outright. Choose **Client certificate (mTLS)** as the authentication method (or `DB_AUTH_MODE=certificate`) and BetterDB sends no `AUTH` at all; username and password are ignored. BetterDB then runs `ACL WHOAMI` after connecting and shows the resolved user in the connection test result and in the connection status (`authenticatedUser`), so you can confirm the certificate mapped to the intended account rather than falling back to `default`.
- Cluster and Sentinel nodes discovered from a seed connection reuse the seed's CA, client certificate and authentication mode. Server certificate verification is always on; there is no option to disable it.
- **Rotation.** File-sourced material (`BETTERDB_TLS_CERT_DIR` paths, and the `DB_TLS_*_FILE` paths of the env-configured connection) is watched for changes: the files are stat-checked at most every few seconds when a socket is opened and re-read when they changed, so a replaced certificate is presented by every new connection (reconnects, key-analytics scans, the CLI, discovered cluster nodes) without a restart. New material is checked to parse as a matching certificate and key before it is adopted, so a rotation caught between writing the two files keeps the previous pair until both are in place. Already-open sockets keep running on the old handshake until they reconnect; use `POST /connections/{id}/reconnect` to force that. While `DB_HOST` is set, the env-configured default connection and the nodes auto-registered from it are rebuilt from the current `DB_*` settings on every start, so a changed username, password, `DB_TLS`, certificate paths or `DB_AUTH_MODE` always win over the stored copy (connections you created yourself keep their own settings, even when they were adopted into the default's topology). Pasted PEM is fixed at save time; re-create the connection to rotate it.
- ### SSH Tunnels
- Connections can reach a database through an SSH bastion/jump host instead of connecting directly — useful for Valkey/Redis in a private subnet, ElastiCache, or MemoryDB. Enable **Connect via SSH tunnel** when adding a connection and provide the SSH host, port, and username. A single hop is supported.
- Authentication is either a password or a private key. Private keys come from one of two sources:
- - **Paste key** (inline): the PEM key content is submitted with the connection. It is stored encrypted at rest **only when `ENCRYPTION_KEY` is set** (envelope encryption); without that key it is stored in plaintext, like connection passwords. Works everywhere, including managed/cloud deployments.
- - **Server file path**: the key already lives on the monitor server's filesystem and is referenced by path. This requires setting the `BETTERDB_SSH_KEY_DIR` environment variable to the directory holding the allowed keys, and the referenced path must resolve inside it, so the API can never be coerced into reading arbitrary files. Leave `BETTERDB_SSH_KEY_DIR` unset to disable this option.
- Optionally pin the SSH server's **host key fingerprint** (`SHA256:...`) on the connection; when set, the tunnel is refused unless the server presents a matching key, preventing man-in-the-middle attacks on the bastion path. Left blank, the server identity is not verified (a warning is logged).
- The tunnel forwards to the database over `127.0.0.1`; when TLS is enabled the certificate is still validated against the real database hostname. Set `ENCRYPTION_KEY` so SSH passwords, key passphrases, and inline keys are encrypted at rest.
- **Known limitation — cluster/Sentinel topologies:** only the connection you configure is tunnelled. Cluster and Sentinel monitoring fan out to the other nodes using the addresses those nodes advertise (`CLUSTER NODES` / Sentinel), and those per-node connections are made directly, not through the tunnel. If the other nodes are only reachable via the bastion (e.g. ElastiCache/MemoryDB in a private subnet), per-node views will be unavailable. Use SSH tunnels for single-node/primary monitoring, or place the monitor where it can reach the cluster nodes directly.
- ### Licensing & Air-Gapped Support
- BetterDB Monitor unlocks Pro/Enterprise features in one of two ways, depending on
- whether the host has internet access:
- - **Online license key** - set `BETTERDB_LICENSE_KEY`. The monitor validates it
- against `betterdb.com` and caches a locally-verified **signed token**, so your
- tier keeps working through short outages and restarts.
- - **Offline / air-gapped license token** - for hosts with **no internet access at
- all** (see below).
- #### How air-gapped licensing works
- Every entitlement is a **signed RS256 JWT**. The monitor verifies it **locally**
- against public keys embedded in the image - it never has to reach a license server
- to trust a token. So an air-gapped host can run paid tiers with zero connectivity:
- 1. On an internet-connected machine, sign in at
- [betterdb.com/account/licenses](https://www.betterdb.com/account/licenses) and
- **download your offline license token** (`.jwt`, Pro/Enterprise). It contains no
- secrets and can't be tampered with - any edit breaks the signature.
- 2. Transfer it to the air-gapped host however you like (USB, config management, a
- Docker/Kubernetes secret mount).
- 3. Provide it via `BETTERDB_OFFLINE_LICENSE_FILE` (path), `BETTERDB_OFFLINE_LICENSE`
- (inline string), or paste it in the UI under **Settings → License → "Air-gapped
- environment? Activate an offline license."**
- When an offline token is configured and **no** `BETTERDB_LICENSE_KEY` is set, the
- monitor makes **zero outbound requests** - license checks, telemetry, and update
- pings are all disabled. It runs the granted tier until the token expires (perpetual
- licenses re-download yearly), then reverts to Community.
- ```bash
- # fully offline - no network required
- docker volume create betterdb-data
- docker run --rm -v betterdb-data:/d alpine chown 1001:1001 /d # volume writable by UID 1001 (one-time)
- docker run -d --name betterdb-monitor -p 3001:3001 \
- -e DB_HOST=your-valkey-host -e DB_PORT=6379 -e DB_PASSWORD=your-password \
- -v /path/to/betterdb-license.jwt:/run/secrets/betterdb-license.jwt:ro \
- -e BETTERDB_OFFLINE_LICENSE_FILE=/run/secrets/betterdb-license.jwt \
- -v betterdb-data:/app/data \
- betterdb/monitor
- ```
- Verify with `GET /api/license/status` → `source: offline-token`, `mode: offline`,
- `airGapped: true`.
- > **Persistence:** mount a writable volume at `/app/data` so the offline license and
- > the online outage-grace token survive restarts. The container runs as **UID 1001**,
- > so a freshly-created volume must be `chown`ed to it (shown above) - otherwise
- > persistence fails with `EACCES … license.jwt`.
- For the full flow, verification precedence, and key-rotation runbook see
- **[Offline & Air-Gapped Licenses](docs/offline-licenses.md)** and the
- **[Configuration reference](docs/configuration.md#license-configuration)**.
- ### Docker Image Details
- - **Base Image**: `node:20-alpine`
- - **Compressed size**: ~360MB (`latest` / `-no-ai`) / ~640MB (versioned image with the experimental AI Helper's local-LLM dependencies)
- - **Platforms**: `linux/amd64`, `linux/arm64`
- - **Contains**: Backend API + Frontend static files (served by Fastify)
- - **Excluded**: SQLite support (use PostgreSQL or Memory storage)
- ### Container Operations
- ```bash
- docker logs -f betterdb-monitor # follow logs
- docker stop betterdb-monitor # stop
- docker rm betterdb-monitor # remove
- ```
- ## Storage Backends
- BetterDB Monitor persists audit trail, analytics, captures, and anomaly data to one of four backends:
- | Backend | Use case | Notes |
- |---------|----------|-------|
- | `memory` | Testing, ephemeral environments | Default in Docker; all data lost on restart |
- | `postgres` | Production | `STORAGE_TYPE=postgres` + `STORAGE_URL=postgresql://user:pass@host:port/db` |
- | `turso` | Production / serverless SQLite | `STORAGE_TYPE=turso` + `STORAGE_URL=libsql://...` + `STORAGE_AUTH_TOKEN`; works in Docker |
- | `sqlite` | Local development / CLI | Native module stripped from the `latest` Docker image; `STORAGE_SQLITE_FILEPATH` optional |
- ## Prometheus Metrics
- Metrics are exposed at `GET /api/prometheus/metrics` in Prometheus text format: ACL audit, client connections, slowlog/commandlog patterns, memory, throughput, keyspace, replication, cluster slot stats, and Node.js runtime metrics - all prefixed `betterdb_`.
- ```yaml
- scrape_configs:
- - job_name: 'betterdb-monitor'
- metrics_path: '/api/prometheus/metrics'
- static_configs:
- - targets: ['your-monitor-host:3001']
- ```
- Full metric reference: [docs/prometheus-metrics.md](docs/prometheus-metrics.md) and [docs/prometheus-integration.md](docs/prometheus-integration.md).
- ## Development
- ### Project Structure
- ```
- betterdb-monitor/
- ├── apps/
- │ ├── api/ # NestJS backend (Fastify)
- │ └── web/ # React frontend (Vite)
- ├── packages/ # Published packages (see below)
- ├── docs/ # Documentation site (Jekyll)
- ├── docker-compose.yml # Local Valkey (port 6380) and Redis (port 6382) for testing
- └── package.json # Workspace root
- ```
- ### Packages
- This monorepo ships several standalone packages. See [`packages/`](packages/) for the full list.
- | Package | Language | Registry |
- |---|---|---|
- | [`@betterdb/monitor`](packages/cli) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/monitor) |
- | [`@betterdb/mcp`](packages/mcp) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/mcp) |
- | [`@betterdb/agent`](packages/agent) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/agent) |
- | [`@betterdb/semantic-cache`](packages/semantic-cache) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/semantic-cache) |
- | [`betterdb-semantic-cache`](packages/semantic-cache-py) | Python | [PyPI](https://pypi.org/project/betterdb-semantic-cache/) |
- | [`@betterdb/agent-cache`](packages/agent-cache) | TypeScript | [npm](https://www.npmjs.com/package/@betterdb/agent-cache) |
- | [`betterdb-agent-cache`](packages/agent-cache-py) | Python | [PyPI](https://pypi.org/project/betterdb-agent-cache/) |
- | [`cache-benchmark`](packages/cache-benchmark) | Python | Replay harness for benchmarking semantic caches |
- ### Tech Stack
- - **Backend**: NestJS with Fastify adapter, `iovalkey` for Valkey/Redis connections, TypeScript strict mode. Port **3001**.
- - **Frontend**: React + TypeScript, Vite, TailwindCSS, Recharts. Dev server on port **5173**.
- - **Monorepo**: pnpm workspaces + Turborepo.
- ### Local Setup
- Prerequisites: Node.js >= 20.0.0, pnpm >= 9.0.0, Docker.
- ```bash
- pnpm install
- cp .env.example .env
- pnpm docker:dev # local Valkey (6380) and Redis (6382)
- pnpm dev # web on :5173, api on :3001
- ```
- To connect to Redis instead of Valkey, set `DB_PORT=6382` in `.env`.
- ```bash
- pnpm dev:api # API only
- pnpm dev:web # frontend only
- pnpm docker:dev:down # stop local databases
- pnpm build # production build
- pnpm test # API tests
- ```
- Docker image builds:
- ```bash
- pnpm docker:build # local build
- pnpm docker:publish # multi-arch build & push (requires buildx)
- ```
- ### Adding New Features
- 1. Add new endpoints in `apps/api/src/`
- 2. Add corresponding API calls in `apps/web/src/api/`
- 3. Add shared types in `packages/shared/src/types/`
- ### Code Style
- - TypeScript strict mode, explicit return types, no `any`
- - ESLint + Prettier configured
- ## License
- - Content under `docs/` is licensed under CC BY-SA 4.0.
- - Content under `proprietary/` is covered by a commercial license (see `proprietary/LICENSE`). These features are free during early access.
- - Everything else is [MIT](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.