Chartbrew: a dashboard builder that reads your database directly

What it is, in the project's own words

The README's central sentence defines the scope: an open source web application that connects directly to databases and APIs and uses the data to create charts. The feature list that follows names a chart builder, editable dashboards, embedable charts, a query and requests editor, and team capabilities.

That list is ordered by how much work it removes. A dashboard that only reads a Postgres table still needs a query layer, a refresh policy, a sharing story and a place for filters. Chartbrew folds the query and requests editor into the same UI as the chart builder, which is why it lists API and NoSQL stores alongside SQL rather than treating an API response as a second class source.

The topic tags describe the stack as much as the product: analytics, api, chartjs, charts, dashboard, data-visualization, then the implementation markers firebase, firebase-firestore, firestore, mongo, mongodb, mysql, nodejs, postgresql, react, reactjs, realtime-database and redux. Two of those deserve comment. Firestore appears both as a supported data source and as an inherited tag from the project's origin, and React with Redux on the client is the older of the two charting stacks most dashboards pick.

The README is a pointer rather than a manual. Installation, configuration and the supported source list are all delegated to docs.chartbrew.com, with the supported data source list deferred to the website, which is a reasonable division for a project of this size but means the GitHub page alone will not get you running.

Prerequisites and local setup are three commands

The prerequisites are specific: NodeJS v22 or newer, MySQL 5 or newer or PostgreSQL 12.5 or newer, and Redis v6 or newer. Redis is the one that surprises people, because it is not optional decoration. It backs the BullMQ queues that drive scheduled refreshes, and the BullMQ admin dashboard at `/apps/queues` is protected with HTTP Basic Auth, with the username defaulting to `chartbrew` on local installs and a random password generated on first startup.

Local setup is a clone and one setup script.

git clone https://github.com/chartbrew/chartbrew.git
cd chartbrew && npm run setup

The `setup` script in the root package.json does three things in order: it runs `prepareSettings`, installs root dependencies, then installs in `client` and then in `server`. `prepareSettings` is the interesting one, because it copies `.env-template` to `.env` and copies `src/config/settings.template.js` to `src/config/settings.js`, both with a prompt that defaults to not overwriting. That last detail matters: the command is `echo n | cp -vipr`, so an existing local config survives a re-run.

Development then runs as two processes in two terminals, which matches the monorepo layout rather than pretending it is a single app.

# frontend
cd client/
npm run start

# backend
cd server/
npm run start-dev

The app comes up on port 4018, and you create the first user account through the UI. Port 4019 is the API. Those two ports recur in the Docker section, and they are also the ports you have to keep consistent with the `VITE_APP_CLIENT_HOST` and `VITE_APP_API_HOST` variables in `.env`, which is a real footgun when you remap them.

The Docker path and the one secret you have to generate

An image is published on Docker Hub on every release, and the README makes an unusual and sensible demand before you run it: you need a 32 byte AES encryption key, and it tells you how to make one rather than asking you to invent a passphrase.

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

The run command then passes an unusually long environment list, and reading it tells you how the service is wired: `CB_API_HOST` and `CB_API_PORT` for the API listener, four `CB_DB_*` values for the metadata database, `CB_REDIS_*` for the queue store, the two BullMQ auth variables, and the `VITE_APP_*` values that tell the frontend where to find itself and the API.

docker run -p 4019:4019 -p 4018:4018 \
  -e CB_ENCRYPTION_KEY=your_32_bytes_key \
  -e CB_BULLMQ_USERNAME=chartbrew \
  -e CB_BULLMQ_PASSWORD=your_strong_random_password \
  -e CB_API_HOST=0.0.0.0 \
  -e CB_API_PORT=4019 \
  -e CB_DB_HOST=host.docker.internal \
  -e CB_DB_PORT=3306 \
  -e CB_DB_NAME=chartbrew \
  -e CB_DB_USERNAME=root \
  -e CB_DB_PASSWORD=password \
  -e CB_REDIS_HOST=host.docker.internal \
  -e CB_REDIS_PORT=6379 \
  -e CB_REDIS_PASSWORD=password \
  -e VITE_APP_CLIENT_HOST=http://localhost:4018 \
  -e VITE_APP_CLIENT_PORT=4018 \
  -e VITE_APP_API_HOST=http://localhost:4019 \
  razvanilin/chartbrew

Note the assumption baked in: MySQL and Redis are already running elsewhere on the host, and the database name has to match `CB_DB_NAME`. The bundled compose file takes the opposite approach and brings its own database along, on `mysql:8.4` with `redis:alpine`, and it does two things the manual command does not. The database has a healthcheck using `mysqladmin ping`, and the app declares `condition: service_healthy`, so the app waits for a database that can actually answer instead of retrying into a crash loop. The compose file also publishes Redis on 6379 to the host, which is convenient for development and worth removing for anything facing a network you do not control.

The Dockerfile is short and readable: a `node:22-slim` base, separate installs in `client` and `server`, `npm run prepareSettings` to seed config inside the image, a production client build, both ports exposed, and `entrypoint.sh` as the entry point.

The semantic visualization engine is the real change of direction

The July 2026 release, v5.3.0, is the one that explains what the project is becoming. The headline is a new semantic visualization engine, described as letting charts generate multiple stable series from a single dataset using a Break down by field. Alongside it came a redesigned chart data configuration with semantic controls for grouping, values, aggregation, breakdowns, missing values, series limits, goals, colors, visibility and ordering.

That word stable in the release note is doing a lot of work, and it points at a real class of bug in dashboarding tools. When a chart is configured as raw query plus raw column mapping, the same data reshuffles whenever the underlying query returns columns in a different order or a new group appears, and the colours you chose end up attached to the wrong series. A semantic layer with explicit identity for each series is the fix, and it is why the release also adds stable colour, visibility and ordering controls for generated series.

Migration was handled as a product concern rather than a breaking change: existing charts are automatically migrated to the new visualization format without manual conversion. The follow-up release, v5.3.1, added a manual migration step in the chart editor as well, and fixed a migration problem for some charts, which suggests the automatic path did not cover every case.

The surrounding improvements are the sort that come from real usage. Tooltips for formulas that return text. Custom ordering for dashboard filters with a unified appearance. Date range filters that apply to all charts by default, with per chart selection moved under advanced settings. Totals in the centre of doughnut charts, plus a choice between percentages and values on segments.

v5.3.1 also added a Dataset Intelligence model, described as helping the AI orchestrator understand your data format better. Every dataset gets one attached automatically and it can be edited from the dataset editor screen. The stated benefit is that the AI reuses datasets better and works much faster. Reading it as architecture: Chartbrew now keeps a machine readable description of each dataset's shape, and the AI features read that description instead of inferring the schema from scratch on every request.

The September release is a security release, and the list is instructive

v5.3.2, published 2026-09-20, carries a warning at the top of the changelog asking users to update as soon as possible, and the substance is nine security patches rather than features. What they protect is worth reading as a map of where a self hosted dashboard is exposed.

Four of them are about tenancy. Team boundaries were strengthened for chart previews, template imports and dataset queries, which are the three paths where one team's data can leak into another's view if ownership is checked in only one place. Unauthorized team ownership changes through role updates and invitations were prevented. Share policy restrictions were enforced on public report variables, so a public report cannot be used as a channel for private variables. And previous team connections are now cleared when the Slack app is reinstalled.

Three are about the integrations, which is the usual weak spot. Slack requests must now carry valid signatures, gated on a new `CB_SLACK_SIGNING_SECRET` variable, and Slack credentials are protected with restrictions on who can update integration settings. Outbound network restrictions were applied to alert and snapshot webhooks, so a webhook target cannot be pointed at internal addresses.

The last two are about the data layer. MongoDB queries are restricted to supported read only operations, which closes the gap where an editable query in the UI could write or delete. Additional private network bypasses were blocked, again on the webhook and outbound path.

The configuration section notes one operational consequence: after reinstalling the Slack app you must run `/chartbrew connect` and select the allowed channels again. That is the correct trade for requiring signatures, since the old installation tokens stop being meaningful once a signature is required, but it will catch people who upgrade and then wonder why Slack stopped reporting.

Two license files, a lerna workspace and a repository that documents its own rules

The licensing needs a sentence of its own, because the tree contains `LICENSE.md` and `LICENSE-FSL.md`, and the repository metadata reports no clear single license as a result. The root package.json still declares MIT, which is the older and simpler position, while the functional source license file is the newer one. Anyone planning to deploy this internally or build on it should read both rather than relying on the package.json field, and the distinction between a permissive license and a functional source license matters most if you have no intention of contributing changes back.

The rest of the tree shows how the project is organised. It is a Lerna workspace with `client/` and `server/` at the root, alongside `docs/`, `scripts/`, `contributors/`, an `ecosystem.config.js` for PM2, `changeVersion.sh` for versioning, and an `entrypoint.sh` for the container. There are separate `.env-template` and `.nvmrc` files, so the Node version is pinned rather than implied, and the Dockerfile independently lands on `node:22-slim`.

The presence of `AGENTS.md`, a `.cursor/` directory, `.vscode/`, `.impeccable.md` and `CLA.md` is a signal about how the project is worked on now. Coding guidance and a contributor licence agreement living in the repository is what a project looks like once it has contributors and needs their contributions to carry the same terms as the codebase. `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` and `SECURITY.md` complete the set, and the last of those matters given what v5.3.2 contained.

There is also a `source-plugin-guide.md`, and a `docker-compose-postgres.yml` beside the MySQL compose file, so the Postgres path is a first class deployment target rather than a documentation promise. There is a DigitalOcean one click droplet referenced from the README as well.

At the time of writing the repository has 4,061 stars, 455 forks, three open issues, is not archived, and was last pushed on 2026-09-20. Three open issues on a project this size is either excellent triage or a very quiet issue tracker, and the repository does not say which.

Editorial conclusion

Chartbrew is the rare self hosted dashboard tool that treats the query layer as part of the product rather than a bolt on, so the same tool covers an application database, a REST API and a document store without you writing glue code for each. Two things follow from the current state of the repository. The version line moved to a semantic visualization engine in July 2026, which changed how charts are configured and how series are generated, and the September release is a security release with nine patches around team boundaries, Slack request signing, MongoDB query restrictions and outbound webhook limits, so anyone running an older build has an upgrade queued up. Licensing is the other loose end: the repository carries both a permissive file and a functional source license, which is a change from the MIT only history and worth reading before you plan around it. With 4,061 stars, 455 forks, three open issues and a push on 2026-09-20, this is an actively maintained project with a security conscious release cadence.

Frequently asked questions

Official sources

1. chartbrew/chartbrew on GitHub
2. Issues
3. Project website
4. README
5. Releases