Chartbrew Docs

Use this guide for a new installation on a Linux server. For an existing v5 installation, use the migration guide.

Prerequisites

Git, npm, and Node.js 22.23.4 or later in the Node.js 22 series. The repository’s .nvmrc selects the project version.
A MySQL or PostgreSQL database and a user that can create and change tables. See Database configuration.
Redis, reachable from the API.
Permission to install Chromium system dependencies for chart image rendering.

Run Chartbrew as a dedicated operating-system user. Use that same user to install dependencies and run the application. For existing installations, update Node.js to include the October 2026 security fixes. Run nvm install and nvm use from the updated repository root, then restart the API and worker processes with the updated Node.js executable. Updating .nvmrc alone does not update a running process.

1. Get the release

Replace YOUR_RELEASE_TAG with the tag you want to install from Chartbrew releases.

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

The setup command installs dependencies and prepares .env and the client settings. The server install step also installs Chromium through Playwright. If that step fails, correct the reported system dependency or permission error, then run:

npm --prefix server run install:playwright

2. Set production configuration

Edit .env in the project root. Set the production values without the _DEV suffix.

Settings	Purpose
`CB_DB_*`	Connect to the Chartbrew database. Use `CB_DB_DIALECT=postgres` and port `5432` for PostgreSQL, or `mysql` and port `3306` for MySQL.
`CB_REDIS_HOST`, `CB_REDIS_PORT`, `CB_REDIS_PASSWORD`	Connect to Redis.
`CB_API_HOST`, `CB_API_PORT`	Set the API bind address and port. Use `127.0.0.1` and `4019` when a reverse proxy runs on the same server.
`VITE_APP_CLIENT_HOST`	Set the public client URL, such as `https://charts.example.com`.
`VITE_APP_API_HOST`	Set the public API URL, such as `https://charts-api.example.com`.
`VITE_APP_CLIENT_PORT`	Set the local client port, such as `4018`.

Generate the encryption key

For a new installation, generate a key and copy it into CB_ENCRYPTION_KEY:

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

Keep this 64-character hexadecimal value in a secure backup. Do not regenerate it during upgrades. Replace the template’s CB_SECRET placeholder with a separate random value for a new installation; keep the existing value for an upgrade. Set CB_BULLMQ_USERNAME and CB_BULLMQ_PASSWORD to protect the queue dashboard. If they are empty and .env is writable, startup fills them in automatically. See Environment variables for SMTP and optional integrations.

chmod 600 .env

3. Build and prepare the database

Run these commands from the project root:

npm --prefix client run build
NODE_ENV=production npm --prefix server run db:migrate
npm --prefix server run image:smoke

The client build is written to client/dist. The API runs directly from its source files. Stop if a command fails and correct the error before you start the services. Client environment values are included at build time. Never put passwords or server secrets in a VITE_APP_* variable. Rebuild the client whenever its public URLs change.

4. Run with PM2

This example uses PM2 to keep one API process and one static client server running. From the project root:

npm install -g pm2
cd server
NODE_ENV=production pm2 start index.js --name chartbrew-api
cd ..
pm2 serve client/dist 4018 --name chartbrew-client --spa
pm2 save
pm2 startup

Run the system command printed by pm2 startup to enable startup after a reboot. The --spa option serves index.html for client routes. See PM2’s static server and startup instructions. Keep port 4018 private through your firewall. The API binds to the address set in CB_API_HOST. Configure Domains and HTTPS before you use the installation publicly.

5. Check and maintain the services

pm2 status
pm2 logs chartbrew-api --lines 100

Complete the deployment checks. Back up the database, .env, and server/uploads. After a configuration change, restart the API with pm2 restart chartbrew-api --update-env. Rebuild the client if you changed a VITE_APP_* value. For an application upgrade, stop the API, back up the data, select the release, install dependencies, build, migrate, and restart. Follow the release’s migration notes.

Get Started

Deployment

Integrations

Charts

Architecture

Migrations

Deploy from source