Upgrade instructions

• On-premises
• Cloud
• Helm

Standalone

• Docker (Linux, macOS)

• Docker (Windows)

Cluster

• Docker Compose

• Minikube

Select a card above to open the upgrade guide for your deployment type, then follow its steps for the target version. Each guide includes instructions for pulling the new image and running the upgrade script.

The table below lists all supported upgrade paths. Versions must be upgraded sequentially — you cannot skip versions.

Target version	Upgrade from	Notes
2.3.0	2.2.0	See third-party component updates below
2.2.0	2.1.0	See Bitnami images notice below
2.1.0	2.0.0 or 2.0.1	fromVersion is auto-detected — no longer required
2.0.1	2.0.0	fromVersion: 2.0.0
2.0.0	1.4.0	fromVersion: 1.4.0 — see migration note below
1.4.0	1.3.0	fromVersion: 1.3.0
1.3.0	1.2.1	fromVersion: 1.2.1
1.2.1	1.2.0	fromVersion: 1.2.0
1.2.0	1.1.0	fromVersion: 1.1.0
1.1.0	1.0.0 or 1.0.1	fromVersion: 1.0.0 or 1.0.1

TBMQ v2.3.0 migrates all third-party components from Bitnami images to official open-source alternatives. These changes improve performance, stability, and remove the dependency on Bitnami's image catalog.

These updates follow the modernization plan outlined in the Bitnami Image Migration guide.

Component	TBMQ v2.2.0	TBMQ v2.3.0	Notes
PostgreSQL	postgres:16	postgres:17	Improved performance and resource efficiency. Existing data volumes remain compatible.
Kafka	bitnamilegacy/kafka:3.7.0	apache/kafka:4.0.0	Migrated from Bitnami to the official Apache Kafka image. New volume paths are required.
Redis → Valkey	bitnamilegacy/redis:7.2.5	valkey/valkey:8.0	Migrated from Bitnami Redis to Valkey. A new volume tbmq-valkey-data is introduced.

Before starting, create full backups of your environment — including the PostgreSQL database (for example, using pg_dump) and your Kafka and Redis data volumes if you plan to migrate them.

PostgreSQL is upgraded from 16 to 17. Although existing data volumes remain compatible, you must perform a proper database version upgrade (for example, using pg_upgrade) to ensure data integrity.

Kafka and Redis have been migrated from Bitnami images to official open-source alternatives. The new images use different internal data directories and volume mappings, so existing Bitnami volumes cannot be reused directly. You must either migrate your data manually or start from new, empty volumes.

The standard upgrade script updates only the PostgreSQL database schema and does not include data migration logic for Kafka or Valkey.

TBMQ deployments prior to v2.3.0 use Bitnami images for third-party components such as PostgreSQL, Redis, and Kafka. The Bitnami team has announced important upcoming changes to their catalog that affect these images.

• Starting August 28, 2025, the public docker.io/bitnami registry will only provide a small set of "latest" hardened images for development use.
• All versioned images will be moved to a temporary legacy registry: docker.io/bitnamilegacy. These images will remain available but will not receive updates or security patches.
• The long-term supported solution is Bitnami's new Secure Images (subscription-based).

Recommended: Complete the upgrade to v2.2.0 first (upgrades must be sequential), then continue to v2.3.0, which replaces all Bitnami images with official open-source alternatives. See third-party component updates in v2.3.0 for details.

If you are staying on v2.2.0 for now, update your image references from docker.io/bitnami/... to docker.io/bitnamilegacy/... to avoid disruption after August 28, 2025.

Version 2.0.0 introduces significant improvements, including a migration from PostgreSQL to Redis for storing messages for persistent DEVICE clients. For details, see the architecture documentation.