Migration Guide

This article outlines the steps and considerations required when upgrading the Iotellect platform from version 6.3 to 6.4.

Starting with version 6.4, embedded Cassandra is no longer supported on the Windows platform. This is due to Apache Cassandra 4.0 dropping Windows support entirely.

• Windows-based deployments that previously relied on the embedded Cassandra instance will not start after upgrading to 6.4.

• There is no in-place replacement; an external database instance is now required on Windows.

Use Docker Desktop to run an external Cassandra instance and connect the platform to it.

1. Install Docker Desktop on the Windows host.

2. Pull and run a supported Cassandra image (Cassandra 4.x).

3. Update the platform configuration to point to the external Cassandra instance (host, port, credentials).

4. Verify connectivity before starting the upgraded platform.

Linux and macOS deployments are unaffected and may continue to use the embedded Cassandra if applicable.

The Platform API has been updated in version 6.4. Any custom plugins built against 6.3 or earlier are not binary-compatible with 6.4 and must be rebuilt.

• Plugins compiled against the 6.3 API will fail to load or behave unexpectedly under 6.4.

1. Update the plugin project's dependency on the Platform API to the 6.4 version.

2. Resolve any compilation errors caused by API changes.

3. Rebuild the plugin artifacts.

4. Replace the existing plugin binaries in your deployment with the newly built versions.

5. Run the plugin's test suite (if available) to confirm correct behavior.

Perform the plugin rebuild and validation in a staging environment before deploying to production.

Several plugins have been relocated from the context folder to the device folder in 6.4. The plugins affected include, but are not limited to:

• context-device-servers

• context-http-server

• If old plugin files remain in the context folder after the upgrade, conflicts or duplicate registrations may occur.

After upgrading to 6.4, manually remove the affected plugins from the context folder. The new versions will be loaded automatically from the device folder.

1. Stop the platform service.

2. Navigate to the context folder of your installation.

3. Delete the legacy plugin files (e.g. context-device-servers, context-http-server, and any other plugins now provided under device).

4. Verify the corresponding plugins are present in the device folder.

5. Start the platform service and check the logs for successful plugin initialization.

1. Back up your current 6.3 installation, configuration, and data.

2. Review and prepare for the changes listed above.

3. On Windows: provision an external Cassandra instance via Docker Desktop and update configuration.

4. Rebuild all custom plugins against the 6.4 Platform API.

5. Stop the 6.3 platform service.

6. Install or upgrade to platform version 6.4.

7. Remove legacy plugins from the context folder.

8. Deploy rebuilt custom plugins.

9. Start the 6.4 platform and validate:

   • Database connectivity

   • Plugin loading (both built-in and custom)

   • Application functionality

10. Monitor logs and metrics for several cycles after the upgrade.

If issues are encountered, rollback to 6.3 is possible only if:

• A backup of the 6.3 installation and data was taken.

• The original (non-rebuilt) plugins are still available.

It is strongly recommended to test the migration in a non-production environment first.

For additional assistance with the migration, please contact your platform support team or refer to the official 6.4 release notes.

Was this page helpful?

Tell us more

Send

Thank you!