Skip to content

Upgrading an Existing Installation

Cloud

Lime BI in Cloud is updated automatically.

On-Premise

Read this before upgrading from Lime BI 3.x or older

Permissions are restructured on initialization. Lime BI 4 creates a dedicated permissions group with full read access to the database. All other groups — including the default "All Users" group — are blocked from accessing the database after initialization.

  • If your Metabase instance has custom groups with their own permissions, those permissions will be overwritten.
  • Content that is not inside the dedicated collection will be inaccessible to non-admin users.
  • Make sure to move all relevant content into the collection before running initialization (see step 5).

SSO login is introduced. Lime BI 4 uses JWT-based single sign-on so that Lime CRM users can access Metabase without separate credentials. All users who log in via SSO are placed in the dedicated permissions group and will have full read access to the database.

CRM integration access is scoped to the dedicated collection. Only content inside the dedicated collection will be available through the Lime CRM integration — for example when embedding dashboards or listing available content in Lime Admin. Content outside the collection will not be accessible from Lime CRM.

Before you begin

  1. Take a back-up of the Lime BI Postgres database.
  2. When installing the Lime BI service via the terminal, the package version of lime-bi dictates which Metabase version will be installed. Check the overview here if you're interested in a concrete version.

Info

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

Upgrade steps

1. Ensure application config

An application_config.yaml file is required. If one does not already exist, see Lime application config for setup instructions.

2. Upgrade the Lime BI service

  1. Run poetry update lime-bi in the solution, release it and install it.
  2. Uninstall Lime BI using lime-bi uninstall.
  3. Re-install Lime BI using lime-bi install.
  4. Open Lime Admin via the Lime CRM webclient to trigger automatic migration of configs from service config to application config.

3. Update Application Config

All Lime BI configuration must be in application_config.yaml. 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 in order to access Lime BI setup in Lime Admin.
  • config.lime-bi.group_name — the application identifier (eg the-customer-app). Used to match existing Metabase resources during the initialization step. Make sure to not use spaces. Use dash (-) rather than underscore (_).
  • config.lime-bi.site_url — see Site url
  • secrets.lime-bi.embedding_secret_key — see Embedding secret key
  • secrets.lime-bi.jwt_signing_key — see Enable SSO with JWT
  • secrets.lime-bi.admin_username / admin_password — your existing Lime BI admin credentials
  • secrets.lime-bi.application_username / application_password — choose an email and password for the non-admin api user. These must be set before the initialization step.

Info

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

4. Verify database connection display name

The initialization process matches the existing database connection by its display name. It must match the group_name value you set in step 3.

  1. Open Metabase as the admin user.
  2. Click the ⚙️ up to the right and click Admin, Databases.
  3. Click the database name to open its settings.
  4. Click Edit connection details.
  5. Check the Display name field. If it does not match group_name (case sensitive), rename it and click Save changes.

5. Move content to the application collection

The initialization process also matches the collection by name. Locate or create a collection matching group_name, then move all content into it.

  1. In the Metabase main UI, look for a collection matching group_name in the left sidebar under Our analytics.
  2. If it does not exist, click + > Collection. Name it exactly as group_name and set the parent to Our analytics.
  3. Move all questions, dashboards, and sub-collections that should remain accessible into this collection. Select items using checkboxes and click Move at the bottom of the screen, or use the three-dot menu on individual items and select Move.

6. Enable SSO with JWT

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

7. Initialize and sync in Lime Admin

Follow the steps in Initialize Lime BI. The initialization will reuse the existing database connection and collection if their names match group_name. It will create a new permissions group and a new api user.

8. Migrate scheduled syncs

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