Skip to content

Upgrading an Existing Installation

Cloud

Lime BI in Cloud is updated automatically.

On-premise

Before you begin take a back-up of the Lime BI Postgres database.

No new admin user required

You do not need to create a new admin user when upgrading from a previous version.

Never click Initialize and Sync in Lime Admin during an upgrade

Lime BI 4.x reuses the Metabase database you already have, and finds it by the database_id you set in step 5. Initialize and Sync would register a second, empty database and sync into that one instead.

The Setup page has a single button. Once database_id is set it reads Sync, which is the one you want. If it still reads Initialize and Sync after step 5, database_id has not taken effect — correct application_config.yaml rather than clicking it.

Decide about SSO before you begin

Lime BI 4.x adds JWT-based single sign-on, so Lime CRM users reach Metabase without separate credentials.

Turning SSO on is recommended, but optional. Earlier manually created accounts keep working exactly as they do now. You can finish this upgrade without it: skip step 6, and leave jwt_signing_key out of step 5.

0. Upgrade solution

  1. Run poetry update lime-bi in the solution and make a release.
  2. Do not install it on the on-prem server yet.

1. Note the Metabase database id

Lime BI 4.x identifies the Lime BI database by id rather than by name. You will need this id when updating the application config in step 5, so capture it before going further.

  1. Open Metabase as the admin user.
  2. Click the ⚙️ in the top right and click Admin, Databases.
  3. Click the existing Lime BI database (most often named Lime BI) to open its settings.
  4. Read the id from the URL — …/admin/databases/<id>.

2. Create application_config.yaml if missing

An application_config.yaml file is required. If one is already in place, skip ahead. Otherwise see Lime application config for setup instructions.

3. Uninstall the Lime BI service

  1. Uninstall Lime BI using lime-bi service uninstall.

4. Install solution and Lime BI service

  1. Install the updated solution.
  2. Re-install Lime BI using lime-bi install.
  3. Open Lime Admin via the Lime CRM web client to trigger automatic migration of configs from service config to application config.

Install location

The suggested install location is now C:\LimeBI (no space), whereas the previous default was C:\Lime BI. Spaces in the path will likely prevent Lime BI from starting.

5. Update application config

Lime BI now keeps all its configuration in application_config.yaml (older versions split it between service config and application config). See the Lime application config section for the full structure and an example.

The following values need to be set for the upgrade:

  • config.addons.lime_bi — needs to be true to access Lime BI setup in Lime Admin.
  • config.lime-bi.site_url — see Site URL
  • config.lime-bi.database_id — the id you noted in step 1.
  • secrets.lime-bi.embedding_secret_key — see Embedding secret key
  • secrets.lime-bi.jwt_signing_key — only if you are enabling SSO; see Enable SSO with JWT
  • secrets.lime-bi.admin_username / admin_password — your existing Lime BI admin credentials

Clean up legacy service config

When the upgrade is finished and everything is confirmed to be working, clean the Lime BI-related configs out of the service config.

6. Enable SSO with JWT (optional)

SSO is recommended but not required — skip this step and the Metabase logins people use today keep working unchanged.

Migrate manually created Metabase accounts to SSO (if you have any)

Metabase uses the email address as the user name. If you enable SSO and Metabase accounts were created manually in earlier versions, matching the Metabase email addresses is necessary.

Lime BI builds the email address from the Lime CRM user name. Assuming a Lime CRM database named LimeDemo:

Lime CRM user name Login used in Metabase
john.doe@lime.tech john.doe@lime.tech
johnpo johnpo-limedemo@lime-bi.com
LIME\johnpo LIME-johnpo-limedemo@lime-bi.com

A Lime CRM user name that is already an email address is used unchanged.

Anything else becomes <user name>-<database name>@lime-bi.com. The database name is taken from the top-level key in application_config.yaml. Any character that is not a letter, a digit, a dot, an underscore or a hyphen turns into a hyphen, which is why LIME\johnpo in the table becomes LIME-johnpo.

Go through every Metabase account that is still in use:

  1. Using the table above, work out the address Lime BI will send for that user.
  2. Open Metabase, click the ⚙️ in the top right and click Admin settings, People.
  3. If the account's email is not already that address, change it to match.

Warning

If someone signs in via SSO before their account has the right address, Metabase creates a second, empty account, and the old one can no longer be given that address. Their saved questions and dashboards stay on the old account and have to be moved across manually.

Info

Renaming the Lime CRM database changes the address for everyone whose user name is not an email address. They all get new, empty accounts, so a rename means going through this step again.

Turn on JWT

Follow the steps in Enable SSO with JWT to configure JWT authentication in Metabase and add the signing key to application config.

7. Sync in Lime Admin

Trigger a sync from Lime Admin: Settings → Lime BI → Setup → Sync. The sync uses the database id you provided in step 5 and updates the existing Metabase tables/fields to match the current CRM schema.

8. Migrate scheduled syncs

Bat-file scheduling is no longer supported. Migrate to the task handler instead. See Schedule automatic syncs for setup instructions.