> ## Documentation Index > Fetch the complete documentation index at: https://docs.chartbrew.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. > [!WARNING] > > 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](https://docs.chartbrew.com/environment-variables.md) 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`. > [!WARNING] > > 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: ```sh theme={null} 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](https://github.com/chartbrew/chartbrew/releases). ```sh theme={null} 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. ```sh theme={null} 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: ```sh theme={null} 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: ```sh theme={null} npm --prefix server run image:smoke ``` ### 3. Apply database migrations With all application instances stopped, run the migration once against the production database: ```sh theme={null} 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. > [!NOTE] > > 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: ```sh theme={null} npm --prefix server start ``` See [Build and deploy](https://docs.chartbrew.com/deployment/build-and-deploy.md) 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. > [!WARNING] > > 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`. ```sh theme={null} 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](https://hub.docker.com/r/razvanilin/chartbrew/tags). Then run: ```sh theme={null} 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](https://docs.chartbrew.com/deployment/run-on-docker.md) 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.