Migration Guide

General case

1. Model Compatibility

Even the oldest models are compatible with the latest versions. However, you may need to perform minor manual adjustments to ensure everything functions correctly.

2. Rendering Engine Changes

The internal graphics rendering engine has been updated. Consequently:

• Certain charts or visualizations might render differently.
• Some custom graphics might require minor CSS or configuration tweaks.

Special case: Version 12 to Version 14+

Overview

However, the jump from version 12 to 14 represents a significant architectural shift. This migration is a specific case in the Lodex lifecycle. While Lodex generally prioritizes backward compatibility (for instance, older JSON models remain compatible with newer versions), the transition from v12 to v14 (skipping v13) involves structural changes to the database.

The primary driver for this change was to decouple Lodex from the EzMaster software, which is no longer maintained. Starting with version 14, Lodex can operate independently of EzMaster, though it can still coexist with it during a transition period.

Database Structure Change: Unlike standard updates, moving from v12 to v14+ requires renaming all MongoDB collections used by Lodex.

Migration Methods

To move your data from v12 to v14 (or v15/v16), you can choose between an automated script or a manual migration.

Method 1: Automatic Migration (Recommended)

We provide a dedicated shell script to handle the renaming of database collections automatically. This is the fastest way to migrate an existing instance.

• Migration Script: migrate-tenant.sh

Instructions:

1. Ensure you have a full backup of your MongoDB database.
2. Run the script against your target database/tenant.
3. Restart your Lodex containers using the version 14+ image.

Method 2: Manual Migration (Export/Import)

If you prefer a "clean slate" approach or are moving to a new server:

1. Export: From your v12 instance, export your data models and your datasets.
2. Setup: Install a fresh instance of Lodex v14+.
3. Import: Import the models and data into the new version.
4. Validation: Review each graphic and configuration setting to ensure the rendering matches your requirements.

---

Transitioning away from EzMaster

Since version 14, Lodex no longer requires EzMaster to function. While you can still run v12 and v14+ side-by-side on an EzMaster host to facilitate a gradual transition, the long-term recommendation is to migrate all instances to a standalone Docker deployment.

This independence allows for:

• Better performance and reduced overhead.
• Simplified maintenance.
• Greater flexibility in hosting environments.