Migrate from v5 to v6

Back up your v5 installation, upgrade to v6, and check your dashboards, connections, and reports.

Use this guide to upgrade a self-hosted Chartbrew v5 installation to v6. Keep your existing database and update the environment variable names before you start v6. Chartbrew applies pending database migrations when the production server starts.

Back up the database, configuration, and uploaded files before you start. Test the upgrade on a copy of your database first. To return to v5, restore the backup and the matching v5 application. Do not run v5 against a database that v6 has migrated.

Before you start

• Schedule a maintenance period. Stop all Chartbrew API instances and background workers before the final backup and migration.
• Record the current application version or Docker image tag.
• Back up the Chartbrew MySQL or PostgreSQL database. Check that you can restore it.
• Save your .env file, deployment settings, and any persistent files or volumes used for uploads.
• Keep the encryption key and legacy secret that your database currently uses. If these are stored as CB_ENCRYPTION_KEY_DEV and CB_SECRET_DEV, move their exact values to CB_ENCRYPTION_KEY and CB_SECRET. Do not replace your .env file with .env-template.
• Keep the existing database, Redis, public URL, email, and integration settings.

When you test with a database copy, use a separate Redis instance. Prevent the test installation from sending scheduled reports or other messages to your users.

Requirements and changes

Area	Action
Node.js	For a source installation, use Node.js 22.23.4 or later in the Node.js 22 series. Version 22.23.4 includes the October 2026 security fixes. Use .nvmrc to select the project version.
Database	Use your existing Chartbrew database. The database user must be able to change tables and indexes. Do not create an empty database for this upgrade.
Redis	Keep Redis available for background jobs.
Chart images	The server uses Playwright and Chromium. The server install step installs Chromium and its system dependencies. Check that the runtime user can access the browser installation.
Charts and dashboards	v6 includes changes to chart configuration and dashboard layout. Check existing charts, filters, and report layouts after migration.
Environment variables	Required for all installations: check and update your configuration. v6 no longer reads variables with the _DEV suffix. Follow the steps below before you build, migrate, or start the application.

The environment variables reference explains the main connection and deployment settings.

Update environment variables

All installations must check their environment variables before the v6 upgrade. v6 uses the original variable names in every environment. Variables with the _DEV suffix are no longer supported. NODE_ENV still controls runtime behavior, but it does not select a different set of variable names.

1. Back up your environment files and deployment settings.
2. For each environment, keep the values that the installation currently uses. If it uses _DEV variables, move those values to the names without _DEV, then remove the old entries. If both names exist, replace the original value with the value used by that environment. Do not keep duplicate entries.
3. Check .env, client/.env if present, service-manager settings, Docker settings, hosting secrets, CI configuration, and shell exports. Use separate values for development, test, and production.
4. Check the database, Redis, encryption keys, public URLs, mail, Google, and OpenAI settings. Installations that already use only the original names can keep their values.

Examples:

Previous name	v6 name
CB_DB_NAME_DEV	CB_DB_NAME
CB_DB_USERNAME_DEV	CB_DB_USERNAME
CB_DB_PASSWORD_DEV	CB_DB_PASSWORD
CB_ENCRYPTION_KEY_DEV	CB_ENCRYPTION_KEY
CB_SECRET_DEV	CB_SECRET
CB_REDIS_HOST_DEV	CB_REDIS_HOST
CB_RUNTIME_REDIS_HOST_DEV	CB_RUNTIME_REDIS_HOST
CB_API_PORT_DEV	CB_API_PORT
VITE_APP_CLIENT_HOST_DEV	VITE_APP_CLIENT_HOST
VITE_APP_CLIENT_PORT_DEV	VITE_APP_CLIENT_PORT
VITE_APP_API_HOST_DEV	VITE_APP_API_HOST
CB_OPENAI_API_KEY_DEV	CB_OPENAI_API_KEY

Apply the same rule to every other _DEV variable. Compare the result with the v6 .env-template.

Keep each database paired with its existing CB_ENCRYPTION_KEY and CB_SECRET values. Do not generate new keys for an existing database. A different key can make saved credentials unreadable and invalidate sessions and share links. NODE_ENV=development no longer selects a development database: check CB_DB_* and Redis settings before you run any command. Tests must use an isolated test database because they clear its tables.

For source installations, also update client/src/config/settings.js. This generated file is not replaced by npm run setup when it already exists. Back it up and compare it with client/src/config/settings.template.js from v6. Remove old variable names and preserve any required local changes. If you have no custom settings, replace it with the v6 template:

cp client/src/config/settings.js client/src/config/settings.js.backup
cp client/src/config/settings.template.js client/src/config/settings.js

Rebuild the client after you set the correct VITE_APP_* values. Restart all API instances and workers after the upgrade so that they read the new configuration.

Upgrade from source

Run the following commands from your Chartbrew checkout. Replace YOUR_V6_TAG with the exact tag of the v6 release you want to install.

1. Select the release

Save any local code changes before you change versions. Select a release tag from the Chartbrew releases.

git fetch --tags
git checkout YOUR_V6_TAG

2. Install dependencies and build the client

Keep your existing .env file in the project root. Set the production VITE_APP_* values before you build the client.

npm run setup
npm --prefix client run build

The server install step also installs Chromium. On Linux, installation of system packages can require administrator access. If Chromium installation fails, correct the error and run:

npm --prefix server run install:playwright

Use the same operating-system user for the browser installation and the Chartbrew server. Check image rendering before you continue:

npm --prefix server run image:smoke

3. Apply database migrations

With all application instances stopped, run the migration once against the production database:

NODE_ENV=production npm --prefix server run db:migrate

Wait for the command to complete. If it fails, keep the application stopped and check the error before you retry. Some migrations can make changes before a failure, so do not assume that the database is unchanged.

Production startup also applies pending migrations. The separate command lets you check the result before you start the application. Development startup does not apply migrations automatically. For a development database, use NODE_ENV=development npm --prefix server run db:migrate.

4. Start the application

Restart the API and client through your existing service manager. Serve the new client/dist build. If you start the API directly, run:

npm --prefix server start

See Build and deploy for service setup. Start one API instance first, check its logs, then start any other instances and workers.

Upgrade with Docker

Keep your existing database volumes, environment variables, ports, networks, and file mounts. Do not replace your deployment configuration with the release example without checking the differences.

Do not run docker compose down -v. This can delete your database volume. Do not change the database image version as part of this application upgrade unless you have a separate database upgrade plan.

Docker Compose with a local build

If your Compose service uses build: ., select the v6 source release as shown above. With the application stopped and the backup complete, run these commands from the directory that contains your Compose file. These examples use the service name chartbrew.

docker compose build chartbrew
docker compose run --rm --no-deps --entrypoint sh chartbrew -c 'cd /code/server && NODE_ENV=production npm run db:migrate'
docker compose up -d --no-deps chartbrew
docker compose logs --tail=100 chartbrew

The database and Redis must remain running and reachable. The migration command overrides the normal entrypoint so that it only runs the database migration.

Docker Compose with a published image

If your service uses image:, set it to the exact v6 image tag you want to deploy. Check the available tag in the Chartbrew image repository. Then run:

docker compose pull chartbrew
docker compose run --rm --no-deps --entrypoint sh chartbrew -c 'cd /code/server && NODE_ENV=production npm run db:migrate'
docker compose up -d --no-deps chartbrew
docker compose logs --tail=100 chartbrew

For a deployment that uses docker run, create the replacement container with the selected v6 image and the same settings and mounts. Start only one instance until its automatic migrations complete. See Run on Docker for the container settings.

Check the upgraded installation

Before you end the maintenance period:

1. Check the server logs for database migration errors and chart migration warnings. A server that starts can still have charts that need attention.
2. Sign in with an existing account. Check team access and dashboard permissions.
3. Open representative charts. Check values, dates, time zones, labels, legends, and horizontal bars against v5.
4. Test a data refresh for each connection type you use, including private-network connections.
5. Check dashboard filters, layouts, public reports, password-protected reports, and embedded charts.
6. Test API calls with existing API keys. Check any scripts that read or write chart configuration.
7. Generate a chart image and check a scheduled report. Confirm that background jobs complete through Redis.

Older v5 share links and private connections

Depending on your v5 version, your installation can also have pending migrations for share tokens and private API connections.

• If an old share link fails, create a new share token and update the link or embed. CB_ALLOW_LEGACY_SHARE_TOKENS=1 temporarily permits tokens signed with CB_SECRET. Use it only while you replace old links, then remove it or set it to 0.
• If an API connection to a private host fails, check its private-host permission and your private-network configuration. A pending migration can reset the saved permission. Permit access only to hosts that the connection needs.

Retention settings

v6 includes automatic cleanup for update history and observation data. The defaults keep successful update history for 30 days, failed update history for 90 days, and metric snapshots for 90 days. Review the DATA RETENTION section in the release’s .env-template before startup if you need different periods. A value of 0 disables cleanup for that category.

If you tested an early build with observation monitors, the migration set includes a reset of those monitors and their linked observations. Keep a backup and recreate the monitors after the upgrade.

Return to v5 if the upgrade fails

1. Stop all v6 API instances and workers.
2. Save the failure logs. Keep a separate copy of the current database if you need to investigate it.
3. Restore the database backup made before the upgrade. Restore the matching configuration and uploaded files.
4. Deploy the recorded v5 source release or Docker image.
5. Start v5 and check sign-in, connections, dashboards, and scheduled jobs.

Changes made after the backup will not be present in the restored database. Keep the installation in maintenance until the v6 checks pass to reduce this risk.