How to Upgrade Bold BI (Windows, Linux, Docker, and Kubernetes) and Troubleshooting Common Upgrade Issues

1) Overview

This article explains how to upgrade Bold BI safely across supported deployment types and how to troubleshoot the most common upgrade-related issues.

What an upgrade does

• Updates the application binaries to the target version.
• Updates the Bold BI database schema as required.
• Preserves existing sites, dashboards, schedules, users, and configuration when persistent data is retained.

2) Before You Upgrade (Required for all environments)

Upgrading Bold BI requires careful preparation to avoid downtime or data loss. Before starting, ensure you have planned a maintenance window, backed up all persistent data, and verified system prerequisites.

2.1 Plan a maintenance window

• Announce downtime and prevent active dashboard editing during the upgrade.
• Confirm you have console/SSH access to the host/cluster and database access.

2.2 Back up persistent data (critical)

Bold BI relies on two persistent components:

1. App_Data (files, resources, tenant assets)
2. Database (metadata, settings, intermediate data)

Back up both before upgrading.

Typical App_Data locations (confirm for your environment):

• Windows: {Deployed Location}\BoldServices\App_Data\
• Linux: /var/www/bold-services/application/ (contains application data)
• Docker: Your mounted host path / docker volume used for persistence
• Kubernetes: Your persistent volume / file share (RWX) mounted to the pods

Database backup

• Back up your Bold BI database(s) (Meta DB and intermediate DB if configured separately).
• Ensure the application can reach the database during the upgrade.

2.3 Verify prerequisites

• Verify sufficient disk space for backups and upgrade artifacts.

3) Upgrade Steps - Windows (On‑Premises)

The following steps outline the process to upgrade Bold BI on the Windows platform. This upgrade ensures your existing configuration, data, and tenant assets are preserved while applying the latest updates and enhancements. Before proceeding, confirm that all prerequisites in Section 2 have been completed, including backups and maintenance planning.

3.1 Upgrade procedure

1. Download the latest Bold BI Enterprise installer.
2. Run the installer. When prompted, choose Upgrade.
3. Keep the existing hosting type, install location, and port unless you intentionally want to change them.
4. Install Chromium packages when prompted (needed for Image/PDF export).
5. Install required client libraries (Oracle/PostgreSQL/MySQL/MongoDB) if your connectors need them.
6. After installation, restart IIS / Bold BI services.
7. Validate using the checklist in Section 8.

Note

• If exports (Image/PDF) fail after upgrade, confirm Chromium packages are present (see Troubleshooting).

Refer to the detailed User Guide for upgrading Bold BI on Windows:
https://help.boldbi.com/deploying-bold-bi/deploying-on-windows/upgrade-to-latest/

4) Upgrade Steps - Linux (On‑Premises Package)

The following steps outline the process to upgrade Bold BI on the Linux platform. This upgrade ensures your existing configuration, data, and tenant assets are preserved while applying the latest updates and enhancements. Before proceeding, confirm that all prerequisites in Section 2 have been completed, including backups and maintenance planning.

4.1 Upgrade procedure

1. Install the pv utility:
   • Ubuntu: sudo apt-get install pv
   • CentOS/RHEL: sudo yum install pv
2. (Optional for ETL) Ensure Python 3.9+ and required pip packages are installed as per your ETL setup.
3. Download and extract the latest Bold BI Linux package.
4. Change into the extracted folder (example: BoldBIEnterpriseEdition-Linux).
5. Run the upgrade:

sudo bash install-boldbi.sh -i upgrade

6. If optional client libraries were not installed during the initial deployment, install them after the upgrade as needed.
7. Validate using the checklist in Section 8.

Rollback note (Linux): The upgrade process typically creates a timestamped backup of the existing bold-services folder (commonly under /var/www/).

Refer to the detailed User Guide for upgrading Bold BI on Linux:
https://help.boldbi.com/deploying-bold-bi/deploying-on-linux/upgrade-to-latest/

5) Upgrade Steps - Docker (Docker Compose)

The following steps outline the process to upgrade Bold BI on the Docker platform. This upgrade ensures your existing configuration, data, and tenant assets are preserved while applying the latest updates and enhancements. Before proceeding, confirm that all prerequisites in Section 2 have been completed, including backups and maintenance planning.

5.1 Key principles

• Your deployment must use persistent storage (volumes/host mounts) for Bold BI App_Data (and database data if DB is containerized).
• Upgrading in Docker is typically done by updating the image tag(s) and restarting the stack.

5.2 Upgrade procedure

1. Locate your docker-compose.yml.
2. Back up the data in the same volumes/host paths used by the current stack.
3. Stop the stack:

docker-compose down

4. Update the Bold BI image tag(s) in docker-compose.yml to the target version.
   • For multi-container deployments, update all Bold BI services consistently.
5. Start the upgraded stack:

docker-compose up -d

6. Review logs until startup completes:

docker-compose logs -f boldbi

7. Validate using the checklist in Section 8.

Refer to the detailed User Guide for upgrading Bold BI in Docker deployments:
https://help.boldbi.com/deploying-bold-bi/deploying-on-docker/bold-bi-on-docker/upgrade-image-in-docker-deployment/

6) Upgrade Steps - Kubernetes

The following steps outline the process to upgrade Bold BI on the Kubernetes environment. This upgrade ensures your existing configuration, data, and tenant assets are preserved while applying the latest updates and enhancements. Before proceeding, confirm that all prerequisites in Section 2 have been completed, including backups and maintenance planning.

6.1 Prerequisites

• Ensure PV/file share (RWX) is healthy and backed up.
• Ensure database is reachable and backed up.

6.2 Upgrade using the Kubernetes upgrade script

1. Back up PV/file share contents and database.
2. Download the upgrade script and run it with your current namespace and target version.

Example:

curl -o upgrade.sh https://raw.githubusercontent.com/boldbi/boldbi-kubernetes/<tag>/upgrade/upgrade.sh
./upgrade.sh --version="<target-version>" --namespace="<namespace>"

6.3 Upgrade using Helm

1. Update Helm repo:

helm repo add boldbi https://boldbi.github.io/boldbi-kubernetes
helm repo update

2. Upgrade the existing release:

helm upgrade <RELEASE_NAME> boldbi/bold-common -f <values.yaml> -n <namespace>

3. Monitor rollout and verify all pods become Ready.
4. Validate using the checklist in Section 8.

7) Upgrade Steps - Azure App Service

The following steps outline the process to upgrade Bold BI on the Azure App Service. This upgrade ensures your existing configuration, data, and tenant assets are preserved while applying the latest updates and enhancements. Before proceeding, confirm that all prerequisites in Section 2 have been completed, including backups and maintenance planning.

7.1 Upgrade Procedure

1. Stop the Azure App Service

   • Sign in to the Azure portal.
   • Navigate to App Services and select the Bold BI App Service.
   • In the Overview page, click Stop.

2. Update the Deployment Source

   • Open Deployment Center.
   • Update the deployment source to the required Bold BI release.
   • If the deployment source is already configured, update it to the target release version.
   • Save the changes.

3. Synchronize the Deployment

   • In Deployment Center, click Sync.
   • Wait until the deployment completes successfully.

4. Update Application Configuration (If Required)

   • If the target Bold BI version introduces configuration changes, update the required App Service settings, runtime version, or Path Mappings as described in the release notes before starting the application.

5. Start the Azure App Service

   • Navigate to the Overview page.
   • Click Start.

6. Wait until the App Service status changes to Running.

   • Validate using the checklist in Section 8.

Refer to the detailed User Guide for upgrading Bold BI on Azure App Service:
https://help.boldbi.com/deploying-bold-bi/deploying-on-azure-app-service/upgrade/upgrade-to-latest/

8) Post‑Upgrade Validation Checklist (All Environments)

Perform these checks before ending the maintenance window:

1. Login & Navigation

   • Can you sign in and reach the expected site(s)/tenant(s)?

2. Dashboard Rendering

   • Open multiple dashboards (including a complex one) and confirm visuals render.

3. Schedules / Jobs

   • Trigger one schedule (export/refresh) and confirm completion.

4. Exports (Image/PDF)

   • Validate dashboard export to PDF/Image.

5. Data Connections

   • Test key connectors and refresh extract-mode data sources if used.

6. Embedded Scenarios (if applicable)

   • Confirm embedded dashboards work as expected.

9) Troubleshooting Common Upgrade Issues

Use the symptom-driven sections below. Apply only what matches your environment and architecture.

9.1 Subsites revert to main DNS / Site URL changes after upgrade

Symptoms

• Subsites unexpectedly change their base DNS/domain.

Likely cause

• Stored site URL/domain mismatch in the application’s persisted settings.

Resolution

1. In UMS → Sites, edit the affected site and set the correct Site Domain.
2. If a database error appears while saving, copy the URL/domain shown in the error, open it in a new tab, then save again.
3. Enable Proxy Settings → Lock Site URL to prevent future overwrites.

9.2 Login redirects / signin-oidc loop / SSL warnings after upgrade (reverse proxy)

Symptoms

• Redirect loop during login, SSL warning, dashboards keep loading.

Likely cause

• SSL is terminated at the load balancer/reverse proxy, but Bold BI is receiving HTTP internally without correct forwarded headers.

Resolution

• Update reverse proxy configuration to forward protocol/host correctly.
• Enable reverse proxy support in Bold BI:

BOLD_SERVICES_REVERSE_PROXY=true

Note: The login redirect configuration described in this section is applicable only to the single-container Docker image deployment. If you are using a multi-container Docker, Kubernetes, or other distributed deployment, refer to the corresponding deployment-specific documentation to configure login redirects appropriately.

9.3 Upgrade/init stuck or DB schema not created (older → newer behind proxy)

Symptoms

• Startup never completes, redirect loops, database tables not created/migrated.

Likely cause

• Outdated reverse proxy rules (often from older major versions) blocking modern routing/headers.

Resolution

• Update NGINX/HAProxy/ALB rules to align with the upgraded version (headers, scheme forwarding, remove legacy rewrites).
• Restart services and retry startup.

9.4 Embedded dashboards fail after upgrade (“Server not found”, unknown errors)

Symptoms

• Server works, but embedded dashboards fail in external applications.

Likely cause

• Embedded SDK version mismatch with server version.

Resolution

• Align the embedded SDK with the upgraded server version across all embedding applications.

9.5 AI Assistant not visible in embedded after upgrade (intermittent)

Symptoms

• AI works in Designer but not in embedded view temporarily.

Resolution

• Verify embed configuration enables AI features.
• Restart the hosting application and Bold BI services.
• Re-test after caches/services settle.

9.6 PostgreSQL deadlock errors after upgrade (metrics table)

Symptoms

• PostgreSQL logs show deadlock detected (commonly around metrics updates).

Resolution

• Upgrade to a later service pack/build where the fix is included.

9.7 “View Underlying Data” shows no records after upgrade (format/locale dependent)

Symptoms

• Underlying data shows no rows for dashboards in a specific environment.

Resolution

• Upgrade to the latest version.
• Compare site language/date formats between environments (e.g., QA vs Production).

9.8 ETL / pipelines fail after upgrade: ModuleNotFoundError: pkg_resources

Symptoms

• Pipeline execution fails; Python errors indicate missing pkg_resources.

Likely cause

• Corrupted/incompatible setuptools in Bold BI’s Python virtual environment.

Resolution (example for Windows venv path)

C:\BoldServices\venv\Scripts\python.exe -m pip install --no-cache-dir --force-reinstall setuptools==80.9.0

Then restart Bold BI services and re-run pipelines.

9.9 Kubernetes: Custom widget upgrade utility fails with permission denied

Symptoms

• Custom widget upgrader fails with UnauthorizedAccessException / permission denied.

Resolution (quick recovery)

1. Exec into the relevant pod:

kubectl exec -it <bi-api-pod> -n <namespace> -- bash

2. Fix permissions on the CustomWidgets directory (use least privilege where possible; example below is a fast workaround):

chmod 777 /application/app_data/bi/<site-id>/CustomWidgets/*

3. Retry widget loading/upgrader.

9.10 Kubernetes: Pods in CrashLoopBackOff after upgrade

Triage steps

kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous

Common causes

• DB connectivity issues
• PV mount failures/permissions
• Incorrect environment variables or secrets

10) Chromium Packages (Export Issues)

Symptom: PDF/Image export fails after upgrade.

What to do

• Ensure Chromium packages are installed and the service has access to the required Chromium folder.
• If installation was done offline or Chromium download was skipped, install Chromium manually and restart the relevant services.

11) License Notes (Post‑Upgrade)

• A license key is typically not required during the upgrade process.
• If you see a license warning after upgrade, refresh/activate the license in UMS (online refresh or offline unlock key, depending on your setup).

12) Rollback / Recovery (If you must revert)

1. Stop the Bold BI Services.
2. Downgrade to the previous version of Bold BI. For windows environment, reinstallation is needed because downgrade is not possible.
3. Restore App_Data from your backup to the original path/mount.
4. Restore the database from backup.
5. Restart services/containers/pods.
6. Validate access and dashboard rendering.

13) What to collect if you still need help

Include these in your support request:

• Current version and target version
• Deployment type (Windows/Linux/Docker/Kubernetes) and architecture (reverse proxy, sub-app/prefix, multi-tenant)
• Logs (installer logs, application logs, container/pod logs)
• Reverse proxy/ingress configuration details (headers, TLS termination)
• Confirmation of App_Data and database backup status