- 
- Getting started
- Installation
- 
- Edge Use Cases
- - -{% if docsPrefix contains 'pe/' or docsPrefix contains 'paas/' %} -The **Professional Edition** is the enterprise-grade version tailored for commercial IoT deployments. It includes all the features of the Community Edition and adds advanced capabilities that help accelerate time-to-market, enhance security, improve scalability, and deliver a polished, production-ready solution. This edition is designed for businesses that require high performance, operational reliability, and premium features.
-{% else %} -The **Community Edition** is a free, open-source version. It is a powerful and scalable multi-tenant solution, ideal for teams looking to experiment, test hypotheses, build proof-of-concepts, or launch MVPs without upfront costs. It offers the flexibility and agility needed in development.
-{% endif %} - -If this is your first experience with the platform we recommend to review [what-is-thingsboard](/docs/{{docsPrefix}}getting-started-guides/what-is-thingsboard/) -and [getting started guide](/docs/{{docsPrefix}}getting-started-guides/helloworld/). -You can find more information on the dedicated page. - -## How do I get started? - -{% if docsPrefix contains 'paas/' %} -We recommend to follow the [getting started guide](/docs/{{docsPrefix}}getting-started-guides/helloworld/). -{% else %} -We recommend to [install](/docs/user-guide/install/{{docsPrefix}}installation-options/) ThingsBoard locally on your laptop or PC using Docker -and follow the [getting started guide](/docs/{{docsPrefix}}getting-started-guides/helloworld/). -{% endif %} - -## What can I do with ThingsBoard? - -ThingsBoard provides out-of-the-box IoT solution that will enable server-side infrastructure for your IoT applications. -You can find more information by browsing [guides](/docs/{{docsPrefix}}user-guide/) and [device library](/docs/{{docsPrefix}}/devices-library/). - -{% unless docsPrefix contains 'paas/' %} -## Where can I host ThingsBoard? - -You can host ThingsBoard in the cloud, on-premises or locally on your laptop, PC or even Raspberry Pi. We recommend to get started with Docker installation - - - [Linux & Mac OS](/docs/user-guide/install/{{docsPrefix}}docker/) - - [Windows](/docs/user-guide/install/{{docsPrefix}}docker-windows/) - -You can also take a look at [cluster setup](/docs/user-guide/install/{{docsPrefix}}cluster-setup/) guide. -{% endunless %} - -## How to connect my device? - -ThingsBoard provides -[MQTT](/docs/{{docsPrefix}}reference/mqtt-api), -[CoAP](/docs/{{docsPrefix}}reference/coap-api), -[HTTP](/docs/{{docsPrefix}}reference/http-api), and. -[LwM2M](/docs/{{docsPrefix}}reference/lwm2m-api) protocols support. -**Existing** devices may be connected to the platform using **[ThingsBoard Gateway](/docs/iot-gateway/what-is-iot-gateway/)**. -You can find more information on the [connectivity](/docs/{{docsPrefix}}reference/protocols/) page. - -## Do I need to use an SDK? - -No, many IoT devices can't afford to embed third-party SDK. ThingsBoard provides quite simple API over common IoT protocols. You can choose any client-side library you like or use your own. -Some useful references: - - - [MQTT client-side libraries list](https://github.com/mqtt/mqtt.github.io/wiki/libraries) - - [C-implementation for CoAP](https://libcoap.net/) - -## What about security? - -You can use MQTT (over SSL) or HTTPS protocols for transport encryption. - -Each device has unique access token credentials that is used to setup connection. Credentials type is pluggable, so X.509 certificates support is coming soon. - -## How much devices can ThingsBoard support? - -ThingsBoard platform is horizontally scalable. Each server node in the cluster is unique. -Scalability is achieved using [consistent-hashing](https://en.wikipedia.org/wiki/Consistent_hashing) load balancing algorithm between the cluster nodes. -Actual performance depends on usage scenario of connected devices. -{% unless docsPrefix contains 'paas/' %} -For example, small commodity hardware cluster can support [several millions](/docs/{{docsPrefix}}reference/iot-platform-deployment-scenarios/#1-million-smart-meters-tco) of devices connected over MQTT. -{% endunless %} - -## Where does ThingsBoard store data? - -The data is stored in [Cassandra](https://cassandra.apache.org/) database. Cassandra suites well for storage and querying of time-series data and provides high availability and fault-tolerance. - -## What license type does ThingsBoard use? - -ThingsBoard is licensed under [Apache 2.0 License](https://en.wikipedia.org/wiki/Apache_License#Version_2.0). -It is free for both personal and commercial usage and you can deploy it anywhere. - -## How can I check which version of ThingsBoard I’m currently using? - -{% if page.docsPrefix contains "paas/" or docsPrefix contains "paas/" %} -ThingsBoard Cloud is a fully managed platform that is regularly updated to the latest version by the ThingsBoard team, so you don't need to worry about maintenance or upgrades. -{% elsif page.docsPrefix == "pe/" or docsPrefix == "pe/" %} -There are several ways to check the platform version in ThingsBoard Professional Edition. -The easiest way is to log in as SysAdmin. On the home page, you will find a widget in the bottom-left corner of the screen displaying the current platform version and indicating whether an upgrade is available. - -Alternatively, if you don’t have access to the SysAdmin account, open [White-Labeling](/docs/{{docsPrefix}}user-guide/white-labeling/) tab from the side menu. -Enable the **Show platform name and version** option to see the current version of the platform. -{% else %} -There are several ways to check the platform version in ThingsBoard Community Edition. -The easiest way is to log in as SysAdmin. On the home page, you will find a widget in the bottom-left corner of the screen showing the current platform version and whether an upgrade is available. -{% endif %} - - -## Can I replace the default ThingsBoard logo in the menu? - -{% if page.docsPrefix contains "paas/" or docsPrefix contains "paas/" %} -In the ThingsBoard Cloud, all branding can be configured directly from the user interface using the built-in [White-Labeling](/docs/{{docsPrefix}}user-guide/white-labeling/#customize-thingsboard-web-interface) module. -Here’s what you can do in just a few clicks: -- Replace the ThingsBoard logo and favicon with your own corporate visuals -- Customize login and system pages to greet users with your brand from the start -- Adjust color schemes and styles (primary, accent colors, logo size, CSS tweaks) to match your identity -- Preview changes live before applying them -- Configure custom domain: map your own domain name (e.g., portal.company.com) so users access the platform via your branded URL - -And it doesn’t stop at the logo. With ThingsBoard Cloud you can: -- Set up custom [email templates](/docs/{{docsPrefix}}user-guide/mail-templates/), so all platform notifications reflect your brand -- Add [custom translations](/docs/{{docsPrefix}}user-guide/custom-translation/), ensuring the platform “speaks” your users’ language -- Create [custom menus](/docs/{{docsPrefix}}user-guide/custom-menu/), adapting navigation to your business workflows - -This gives you a fully branded platform: your users see your logo, your colors, your emails, and even your tailored menus. -{% elsif page.docsPrefix == "pe/" or docsPrefix == "pe/" %} -In the Professional Edition, all branding can be configured directly from the user interface using the built-in [White-Labeling](/docs/{{docsPrefix}}user-guide/white-labeling/#customize-thingsboard-web-interface) module. -Here’s what you can do in just a few clicks: -- Replace the ThingsBoard logo and favicon with your own corporate visuals -- Customize login and system pages to greet users with your brand from the start -- Adjust color schemes and styles (primary, accent colors, logo size, CSS tweaks) to match your identity -- Preview changes live before applying them -- Configure custom domains: map your own domain name (e.g., portal.company.com) so users access the platform via your branded URL - -And it doesn’t stop at the logo. With PE you can: -- Set up custom [email templates](/docs/{{docsPrefix}}user-guide/mail-templates/), so all platform notifications reflect your brand -- Add [custom translations](/docs/{{docsPrefix}}user-guide/custom-translation/), ensuring the platform “speaks” your users’ language -- Create [custom menus](/docs/{{docsPrefix}}user-guide/custom-menu/), adapting navigation to your business workflows - -This gives you a fully branded platform: your users see your logo, your colors, your emails, and even your tailored menus. -{% else %} -The Community Edition does not include a built-in white-labeling feature. However, it is technically possible to replace the default ThingsBoard logo by modifying the source code and rebuilding the platform. This requires development expertise and familiarity with ThingsBoard’s codebase. Please note that such changes will need to be reapplied after each upgrade of the platform. - -If you need a more streamlined and configurable option, we recommend considering the Professional Edition. With Professional Edition, you can effortlessly upload your own logo and favicon, customize login and system pages, adjust colors and branding palettes, and even tailor [email templates](/docs/pe/user-guide/mail-templates/), [translations](/docs/pe/user-guide/custom-translation/), and [custom menus](/docs/pe/user-guide/custom-menu/) - all directly from the user interface, without touching the code. This empowers your organization to deliver a fully branded, professional-grade experience to your customers and tenants in just a few clicks. - -More details: [PE White-Labeling Guide](/docs/pe/user-guide/white-labeling/#customize-thingsboard-web-interface). -{% endif %} - -## How to get support? - -You can use troubleshooting instructions and community resources or [contact us](/docs/contact-us) and learn more about [services](/services/) we provide. + + + + +
Open Source IoT Platform
+ +ThingsBoard Professional Edition (PE) is an advanced IoT platform designed for production-grade deployments, offering enterprise features, white-labeling, advanced security, and official support. It is ideal for businesses looking to deploy scalable, reliable IoT solutions with professional backing.
+ThingsBoard is an IoT platform for data collection, processing, visualization, and device management. It provides out-of-the-box components and APIs to significantly accelerate development and lower costs while maintaining control of your solution and data.
+See What is ThingsBoard? to learn more about the platform's architecture and capabilities, or jump to our Getting Started Guide to begin building your first IoT project.
+ {% else %} +ThingsBoard Community Edition (CE) is the free and open-source IoT platform for collecting, storing, analyzing, and visualizing data from IoT devices. It is designed for developers and businesses who want full control over their IoT infrastructure without licensing fees.
+ThingsBoard is an open-source IoT platform for data collection, processing, visualization, and device management. It provides out-of-the-box components and APIs to significantly accelerate development and lower costs while maintaining control of your solution and data.
+See What is ThingsBoard? to learn more about the platform's architecture and capabilities, or jump to our Getting Started Guide to begin building your first IoT project.
+ {% endif %} +No, Professional Edition requires a paid subscription.
+ {% else %} +Yes, it is completely free, with no licensing fees or hidden costs.
+ {% endif %} +Community Edition is free and open-source, suitable for development, testing, and production use without licensing costs. It includes essential features for IoT device management, data collection, visualization, and rule processing.
+Professional Edition includes all features from CE and offers advanced features such as white-labeling, role-based access control (RBAC), platform integrations, solution templates, scheduler, and enterprise support.
+See the PE product page for detailed feature comparison table.
+Yes. CE is licensed under Apache 2.0, allowing commercial use without restrictions. You can build, sell, and deploy commercial products on CE.
+Start with ThingsBoard Cloud for immediate access, or follow our installation guide to deploy PE on your infrastructure.
+To connect your first device and build dashboards, explore the Getting Started Guide.
+ {% else %} +Start with Live Demo for immediate access, or install ThingsBoard CE locally by following installation guide.
+To connect your first device and build dashboards, explore the Getting Started Guide.
+ {% endif %} +Yes, you can migrate from ThingsBoard Community Edition to Professional Edition without losing telemetry data and/or configurations. The upgrade process preserves your existing setup, ensuring a seamless transition.
+However, please note that any custom modifications made directly to the source code of the Community Edition will be removed during the upgrade process.
+See the ThingsBoard instructions for upgrading from Community Edition. Back up your data before starting.
+Limits vary by subscription plan. Cloud plans range from 30 devices (Maker) to unlimited (Enterprise). Self-managed subscriptions range from 10 devices (Maker) to unlimited (Enterprise).
+ {% else %} +No, there are no programmatic limits, but performance depends on your server(s) capacity.
+ {% endif %} +Yes, each Cloud plan has specific API and rate limits. Self-managed plans have no programmatic API limits but depend on infrastructure capacity.
+ {% else %} +No built-in API rate limits in the software itself, but performance depends on infrastructure.
+ {% endif %} +Yes, through REST APIs, Rule Engine, and Platform Integrations (PE-only feature with 30+ built-in connectors for OPC-UA, LoRaWAN networks, cloud platforms, etc.).
+ {% else %} +Yes, you can integrate ThingsBoard Community Edition with third-party systems through REST APIs or Rule Engine.
+ {% endif %} +Yes, white-labeling is available starting from the Prototype plan and above.
+ {% else %} +No, white-labeling is available only in the Professional Edition.
+ {% endif %} +Yes, start a 30 days free trial with Maker plan or request a demo. The trial includes access to all PE features for evaluation.
+Professional Edition is proprietary software. Source code is not publicly available.
+ {% else %} +The source code is available on GitHub. You can fork, modify, and contribute to the project under the Apache 2.0 license.
+ {% endif %} +Professional Edition is closed-source and does not accept external contributions.
+ {% else %} +Yes! Pull requests and contributions are welcome on GitHub. Check the contribution guidelines before submitting.
+ {% endif %} +Add-ons are complementary products that extend ThingsBoard Professional Edition capabilities. They integrate seamlessly with your ThingsBoard instance and require a PE subscription to use. Add-ons include ThingsBoard Edge PE (edge computing), and Trendz Analytics (advanced analytics/AI).
+ThingsBoard Edge is an edge computing solution that runs locally at remote sites, processing data with reduced latency while maintaining sync with your central ThingsBoard server. It operates offline and automatically syncs when connectivity returns.
+Edge Professional Edition, included as an add-on to ThingsBoard PE subscriptions, adds enterprise features such as white-labeling, solution templates, platform integrations, scheduler, and customer hierarchy management to edge computing core capabilities.
+The number of included Edge instances depends on your subscription plan. Additional instances can be purchased separately. Check your plan details or contact us for specifics.
+See Edge documentation for setup and configuration details.
+Trendz Analytics is an advanced analytics platform for ThingsBoard PE that brings anomaly detection, predictive analytics, calculated fields, an AI assistant, Metric Explorer, and rich visualizations into one unified workspace.
+It enables you to analyze IoT data, detect issues, and predict outcomes — all seamlessly integrated with your ThingsBoard environment.
+See Trendz documentation for more information.
+-
+
- Edge: No. Edge edition must match your ThingsBoard Server edition. Edge PE connects to ThingsBoard PE Server. However, you can use Edge CE with ThingsBoard CE Server. It's free and open-source as well as ThingsBoard CE. +
- Trendz Analytics: No, Trendz requires ThingsBoard Professional Edition. +
No, they are both designed to complement the capabilities of ThingsBoard, not to function as standalone solutions. Neither can operate independently:
+-
+
- Edge PE: Requires connection to sync with ThingsBoard PE Server (Cloud, Private Cloud, or self-managed). +
- Trendz Analytics: Requires ThingsBoard PE as its data source. +
Yes,you can start a 30-day trial of the Maker plan with Edge Computing and Trendz add-ons enabled. You'll have full access to add-ons features.
+ThingsBoard Private Cloud is a fully managed, isolated ThingsBoard Professional Edition cluster that our team deploys and operates for you.
+We provision the infrastructure, keep the platform patched and monitored 24×7, run automated backups, and provide an SLA-backed uptime guarantee (99%–99.99%, depending on plan). During onboarding, you choose the region that best fits your compliance or latency requirements—EU, North America, or APAC.
+All environments are hosted in ISO 27001/PCI-DSS-certified data centers. Your engineers can stay focused on building IoT applications instead of managing DevOps.
+Private Cloud provides a dedicated, isolated environment for your organization, whereas ThingsBoard Cloud is a shared multi-tenant SaaS platform. Private Cloud offers enhanced security, custom SLAs, and infrastructure isolation for compliance-sensitive industries.
+Private Cloud offers enhanced security, custom SLAs, and infrastructure isolation for compliance-sensitive industries.
+Private Cloud eliminates operational complexity:
+-
+
- Zero DevOps overhead: No infrastructure management or DevOps required. +
- Guaranteed availability: 99.9-99.99% uptime SLA with service credits. +
- Faster time-to-market: Deployed in 1-2 hours vs. weeks for self-hosting +
- Scalability: Kubernetes infrastructure grows with your traffic +
- Predictable cost: One monthly fee replaces infrastructure and staffing expenses. +
Uptime measures platform availability as a percentage of time services are operational during the billing month.
+Formula: Uptime (%) = ((Total Time – Downtime) / Total Time) × 100.
+Scheduled maintenance, security patches, and issues caused by customer configurations are excluded from downtime calculations.
+Yes, Private Cloud can be deployed in your preferred AWS, Azure, or GCP region to meet data residency and latency requirements.
+ThingsBoard team manages all infrastructure, updates, monitoring, and maintenance. You focus on your IoT application while we handle platform operations.
+Private Cloud includes priority support, dedicated success management, and custom SLA options. Support levels are defined in your service agreement.
+Yes, Private Cloud supports custom configurations including white-labeling, custom domains, and infrastructure scaling to match your requirements.
+Private Cloud is designed to support compliance requirements including GDPR, HIPAA, and ISO 27001
. Specific compliance certifications depend on your deployment configuration and service agreement. +Contact us to discuss your requirements. We'll help you design the right Private Cloud configuration for your use case.
+Yes, ThingsBoard includes an AI Request node in the Rule Engine that allows integration with AI services like OpenAI, Azure OpenAI, and custom AI endpoints.
+Yes, ThingsBoard includes built-in AI integration capabilities. You can use the AI Request node to send telemetry data to machine learning models for predictive analytics, anomaly detection, and maintenance scheduling.
+See predictive maintenance example for implementation details.
+ThingsBoard supports OpenAI, Azure OpenAI, and custom API endpoints. You can integrate any AI service that provides a REST API.
+Yes, export historical telemetry via REST API or data export features (PE) to train models externally. Deploy trained models as API endpoints and integrate them using the AI Request node.
+Yes, see documentation for examples including anomaly detection, and natural language processing.
+ThingsBoard integration is included, but you need subscriptions to external AI services (OpenAI, Azure, etc.) if using those providers. Custom AI endpoints are entirely under your control.
+Yes, the Rule Engine allows batch processing. Aggregate telemetry data and send batched requests to AI endpoints to optimize costs and performance.
+Professional Edition offers three deployment options:
+-
+
- ThingsBoard Cloud: Fully managed SaaS (North America or EU regions) +
- Private Cloud: Dedicated managed instance in your choice of region +
- Self-managed: On your infrastructure—on-premise or cloud (AWS, Azure, GCP, DigitalOcean), Docker, or Kubernetes +
Community Edition can be installed on:
+-
+
- On-premise servers or virtual machines. Docker and Kubernetes deployments are supported. +
- Cloud platforms: AWS, Microsoft Azure, DigitalOcean, Google Cloud Platform +
Yes, clustering is supported in all deployment options.
+ {% else %} +Yes, clustering is fully supported in the Community Edition.
+ {% endif %} +See cluster setup guide for configuration details.
+Minimum: 2 CPU cores, 4GB RAM for testing.
+Recommended for production: 8+ CPU cores, 16GB+ RAM. Requirements scale with device count and message volume.
+Device capacity varies by deployment type:
+-
+
- ThingsBoard Cloud: Plan-based limits (30 devices for Maker up to unlimited for Enterprise). +
- Private Cloud: Plan-based allocations (5K-100K+ devices). +
- Self-managed: No software limits—capacity depends on your infrastructure (tens of thousands on single server, millions in clusters). +
There are no software limits on device count. The number of devices depends on your hardware capacity, database configuration, and deployment architecture (standalone vs cluster). A single server can handle tens of thousands of devices; clustered deployments can scale to millions
+ {% endif %} +ThingsBoard supports two database approaches:
+-
+
- Pure SQL: PostgreSQL database which is default and recommended for development and production environments with reasonable load (< 5000 msg/sec). +
- Hybrid database: PostgreSQL+Cassandra or PostgreSQL+TimescaleDB for 1M+ devices in production or high data ingestion rate (> 5000 msg/sec). +
Yes, ThingsBoard Cloud supports multi-tenancy, with each tenant requiring its own subscription.
+Within a tenant, a customer hierarchy can be established, allowing tenant administrators to manage multiple customers under a single subscription. This structure provides sufficient flexibility and access control for most use cases, ensuring a well-organized and efficient management model.
+ThingsBoard Enterprise subscription offers multi-tenancy within a single plan.
+ {% else %} +Yes, the ThingsBoard Community Edition supports multi-tenancy out of the box.
+ {% endif %} +Yes, the ThingsBoard supports OTA (Over-the-Air) firmware updates.
+API charges depend on your deployment type:
+-
+
- ThingsBoard Cloud & Private Cloud: API requests are included in your subscription with no additional charges +
- Self-managed:: No charges or programmatic limits on API requests. +
No. Community Edition has no charges or limits on API requests. However, performance depends on your server capacity and infrastructure.
+ {% endif %} +API access may be throttled until the next billing cycle, or you can upgrade to a higher plan.
+Yes. Professional Edition offers PE Mobile Application - advanced mobile app with enterprise features and white-labeling.
+ {% else %} +Yes. ThingsBoard Mobile Application is free and open-source (Apache 2.0 license). It's available for iOS and Android and works with ThingsBoard CE Server.
+ {% endif %} +Your data will be retained for a short period before being permanently deleted.
+Security depends on deployment type:
+-
+
- Cloud/Private Cloud deployments are hosted in ISO 27001/SOC 2 compliant infrastructure. +
- Self-managed security depends on your infrastructure setup. It requires you to manage infrastructure security, network configuration, and SSL/TLS setup. +
Yes, but security depends on your deployment setup and infrastructure.
+ {% endif %} +ThingsBoard provides device authentication, encrypted communication (SSL/TLS), role-based access control, and audit logging.
+Yes, transport encryption (TLS/SSL) is supported. Additional encryption features may depend on your subscription plan and deployment type.
+ {% else %} +Yes, the Community Edition includes transport encryption (TLS/SSL).
+ {% endif %} +For data-at-rest encryption, configure database-level encryption. See security documentation for setup instructions.
+Yes, SSO and OAuth are supported with additional enterprise features in PE.
+ {% else %} +Yes, the Community Edition includes SSO (Single Sign-On) and OAuth functionality.
+ {% endif %} +For data-at-rest encryption, configure database-level encryption. See security documentation for setup instructions.
+-
+
- Cloud: Your data is stored in either North America or the EU, depending on the cloud region (US or European) you choose. With the Enterprise subscription, you can choose any region or specific country for data storage. +
- Private Cloud/Self-managed: Yes, you have full control over data storage location. +
Yes, you have full control over where your data is stored.
+ {% endif %} +ThingsBoard supports multiple authentication methods: access tokens, X.509 certificates, and username/password. Each device receives unique credentials. See device authentication options available.
+Community Edition supports a straight-forward security model with three main roles: System administrator, Tenant administrator, and Customer user. A system administrator is able to manage tenants, while a tenant administrator manages devices, dashboards, customers, and other entities that belong to a particular tenant. Customer user is able to view dashboards and control devices that are assigned to a specific customer.
+ {% if page.docsPrefix contains "paas/" or docsPrefix contains "paas/" or page.docsPrefix == "pe/" or docsPrefix == "pe/" %} +Yes, ThingsBoard supports RBAC.
+Professional Edition includes advanced RBAC with custom roles, hierarchical permissions, and group-based access control.
+ {% endif %} +-
+
- Cloud/Private Cloud: Infrastructure is ISO 27001/SOC 2 compliant. GDPR compliance depends on how you configure and use the platform. +
- Self-managed: Compliance depends on your infrastructure and practices. +
Compliance depends on your hosting environment and data security practices.
+ {% endif %} +Yes, ThingsBoard supports OAuth2, LDAP, and SAML integration.
+ {% if page.docsPrefix contains "paas/" or docsPrefix contains "paas/" or page.docsPrefix == "pe/" or docsPrefix == "pe/" %} +Professional Edition includes additional SSO options.
+ {% endif %} +Yes, ThingsBoard logs user actions, API calls, and system events.
+ {% if page.docsPrefix contains "paas/" or docsPrefix contains "paas/" or page.docsPrefix == "pe/" or docsPrefix == "pe/" %} +Professional Edition provides enhanced audit logging with detailed tracking and export capabilities.
+ {% endif %} +Support varies by plan: Cloud Maker/Prototype (community support), Startup+ (email support with SLA), Growth+ (priority support), Enterprise (dedicated support team).
+ {% else %} +The ThingsBoard team does not provide dedicated support for Community Edition users. Support is community-driven through GitHub (report issues, contribute), Stack Overflow (developer questions), Documentation (guides and tutorials), Youtube channel (tutorials).
+ {% endif %} +Yes, ThingsBoard offers consulting, custom development, learning resources, and deployment assistance. Contact us to discuss your requirements.
+Report via Support Portal (for paying customers) or Report bugs on GitHub. Include detailed reproduction steps, logs, and system information.
+ {% else %} +Report bugs on GitHub Issues. Include detailed reproduction steps, logs, and system information. Community members and maintainers will investigate.
+ {% endif %} +Yes, comprehensive documentation, video tutorials, and sample projects are available. Professional services include custom training programs. See learning resources for more.
+Yes, professional services include deployment assistance, architecture review, and production setup. Contact us to discuss your deployment needs.
+MQTT Broker
-## How do I get started? - -We recommend [installing](/docs/mqtt-broker/install/installation-options/) TBMQ locally on your laptop or PC using Docker -and follow the [getting started guide](/docs/mqtt-broker/getting-started/). - -## What can I do with TBMQ? - -TBMQ enables seamless communication between MQTT clients, ensuring reliable data exchange. -It provides robust support for MQTT versions 3.x and 5.0, ensuring compatibility with a wide range of clients. -TBMQ enhances both functionality and scalability, making it suitable for IoT deployments of any size. - -## Where can I host TBMQ? - -The hosting options for TBMQ are highly flexible, allowing you to choose from cloud-based environments, on-premises setups, -or even running it locally on your personal laptop or PC. -For initiating the setup process, we advise opting for the [Docker installation](/docs/mqtt-broker/install/docker/), which offers a streamlined and efficient approach. -If you're interested in configuring a cluster setup, a comprehensive [guide](/docs/mqtt-broker/install/cluster/docker-compose-setup/) is available, specifically designed for Docker Compose setups. - -## What about security? - -TBMQ ensures secure communication by supporting MQTT with SSL/TLS encryption, safeguarding data transmission. -It also allows the creation of client credentials for authentication and authorization, bolstering system security. -With MQTT 5, TBMQ offers enhanced authentication features, enabling more flexible and dynamic client authentication mechanisms. -These measures provide robust protection against unauthorized access and strengthen overall security control in your IoT environment. - -## How many clients and messages per second can TBMQ support? - -TBMQ boasts horizontal scalability, meaning it can be expanded seamlessly to accommodate growing demands. -Each broker, or node, within the cluster possesses identical capabilities and handles a specific subset of the data. -It's worth noting that the actual performance of the system is contingent upon the specific usage scenario, -with factors such as payload size and message rate playing crucial roles in determining the overall efficiency and throughput of the system. -For a comprehensive understanding of the performance capabilities of TBMQ, we recommend referring to the dedicated -[performance test page](/docs/mqtt-broker/reference/100m-connections-performance-test/). - -## Where does TBMQ store data? - -TBMQ utilizes [Kafka](https://kafka.apache.org/), [Redis](https://redis.io/), and [PostgreSQL](https://www.postgresql.org/) for data storage. -Kafka handles unprocessed PUBLISH messages, persistent messages for Application clients, and stores client sessions and subscriptions, ensuring seamless data flow across broker nodes. -Redis is used for Device persistent clients, providing high-performance message storage and delivery. -PostgreSQL stores essential metadata, including user credentials, MQTT client details, and system statistics, ensuring data reliability and integrity. - -## What license type does TBMQ use? - -TBMQ is licensed under Apache 2.0 License. It is free for both personal and commercial usage, and you can deploy it anywhere. - -## How to get support? - -You can use troubleshooting instructions and community resources or [contact us](/docs/contact-us) and learn more about [services](/services/) we provide. +TBMQ is a high-performance MQTT broker developed by ThingsBoard. It enables efficient, reliable, and scalable communication between MQTT clients and IoT applications. TBMQ supports MQTT 3.x and MQTT 5.0, ensuring compatibility with a wide range of devices and industry use cases.
+The broker is available in two editions: Community Edition (CE) and Professional Edition (PE).
+The Community Edition is a free and open-source version, ideal for developers and teams who want to explore, prototype, and test MQTT-based solutions without licensing costs. It provides a robust MQTT broker that can be deployed locally, on-premises, or in the cloud. CE delivers all the essential features for reliable messaging, scalability, and monitoring — making it a perfect starting point for both learning and production-scale use cases.
+If this is your first experience with TBMQ, we recommend reviewing the What is TBMQ and Getting Started Guide to learn more about its architecture, setup, and key capabilities.
+TBMQ is a high-performance MQTT broker developed by ThingsBoard. It enables efficient, reliable, and scalable communication between MQTT clients and IoT applications. TBMQ supports MQTT 3.x and MQTT 5.0, ensuring compatibility with a wide range of devices and industry use cases.
+The broker is available in two editions: Community Edition (CE) and Professional Edition (PE).
+The Professional Edition (PE) is the enterprise-grade version of TBMQ, designed for commercial IoT deployments and large-scale production environments. It includes all the capabilities of the Community Edition, plus advanced features such as:
+-
+
- White-label branding and UI customization +
- Advanced security and access control +
- Enhanced monitoring, analytics, and reporting +
- Professional support and maintenance +
PE is built for organizations that require high throughput, operational reliability, and premium management capabilities to run mission-critical IoT infrastructures.
+If this is your first experience with TBMQ, we recommend reviewing the What is TBMQ and Getting Started Guide to understand its features and deployment options in detail.
+We recommend installing TBMQ locally on your laptop or PC using Docker and following the Getting Started Guide. The guide walks you through installation, configuration, and initial testing, helping you establish your first MQTT connections quickly and reliably.
+You can install TBMQ locally or in the cloud using Docker, Kubernetes scripts, or Helm. Detailed step-by-step guides are available in the Installation Guide, including configuration of Kafka, Redis, and PostgreSQL dependencies.
+To start TBMQ with Docker, run the provided Docker Compose file, which launches all required services (Kafka, Redis, PostgreSQL, and the MQTT broker) in a single command. + For Kubernetes, use the official Helm chart to deploy TBMQ as a scalable, fault-tolerant cluster. The Helm chart includes configurable parameters for persistence, resource limits, and monitoring. + Both methods provide a quick way to get TBMQ running in minutes, whether for testing or production.
+TBMQ can run on modest hardware for testing or small-scale evaluation. The minimum requirements to start TBMQ are:
+-
+
- CPU: 1 core +
- Memory: 2 GB RAM +
However, for stable performance and smoother operation in typical environments, the recommended configuration is:
+-
+
- CPU: 4 cores +
- Memory: 8 GB RAM +
- Storage: 50 GB of free disk space +
- Operating System: Linux (x86-64 architecture) +
For clustered or production environments, hardware needs depend on the expected number of clients and message throughput.
+High-volume setups should allocate dedicated nodes for Kafka, Redis, and PostgreSQL to ensure optimal scalability and reliability.
+Upgrading TBMQ is straightforward. The Upgrade Guide + provides version-specific instructions and notes about compatibility changes or configuration updates introduced in each release.
+For production environments, TBMQ should be configured for performance, security, and fault tolerance. It is recommended to:
+-
+
- Enable SSL/TLS encryption for MQTT and WebSocket connections. +
- Configure authentication providers for secure client validation. +
- Configure an appropriate number of Kafka partitions for each topic, tune producer and consumer parameters, and adjust Redis stateful connection settings to achieve optimal throughput. +
- Tune JVM memory and thread pool settings according to system resources. +
Yes. TBMQ fully supports Kubernetes deployments through the official Helm chart or k8s manifests. This approach provides easy scaling, automatic recovery, and rolling updates. You can configure node roles, persistence volumes, and monitoring integrations directly through Helm values, making it suitable for cloud or hybrid environments.
+TBMQ supports horizontal scaling through clustering. Each node in the cluster handles a portion of MQTT clients and message flow, ensuring reliability and load balancing. Cluster coordination is achieved using Kafka for message routing.
+To enable clustering, deploy multiple TBMQ instances connected to the same Kafka, Redis, and PostgreSQL services, and configure a unique broker ID (TB_SERVICE_ID) in the environment variables per node.
By default, TBMQ listens on the following ports:
+-
+
- 1883 – MQTT (plain TCP) +
- 8883 – MQTT over SSL/TLS +
- 8084 – MQTT over WebSocket +
- 8085 – MQTT over Secure WebSocket (WSS) +
- 8083 - HTTP Web UI access +
These ports can be modified in the TBMQ configuration file or via environment variables before startup. Make sure your firewall or Kubernetes ingress rules allow access to the selected ports.
+You can enable SSL/TLS by providing a valid server certificate and private key in the TBMQ configuration. TBMQ supports both server-side encryption and client certificate authentication (X.509) for stronger security. Certificates can be issued by a trusted CA or generated internally for testing. Once configured, restart the broker to apply the changes.
+TBMQ uses a pluggable authentication model, allowing you to define how clients are authenticated. You can choose between:
+-
+
- Basic authentication (client ID, username, and password) +
- SSL-based authentication (X.509 certificate chain) +
- JWT authentication (JSON Web Tokens) +
- Enhanced authentication (MQTT 5.0) +
Authentication rules are defined in the database and evaluated during each connection attempt.
+TBMQ integrates with Kafka, Redis, and PostgreSQL to ensure reliable, high-performance data storage:
+-
+
- Kafka – handles unprocessed PUBLISH messages, persistent messages for Application clients, and stores client sessions and subscriptions. +
- Redis – stores Device persistent messages for fast access and recovery. +
- PostgreSQL – stores metadata such as user credentials, MQTT client credentials, system statistics, etc. +
This hybrid architecture ensures data durability, high availability, and efficient delivery across distributed systems.
+TBMQ fully supports MQTT 3.1.1 and MQTT 5.0, ensuring compatibility with all major MQTT clients and libraries. Support for MQTT 5.0 introduces advanced features such as shared subscriptions, user properties, topic aliases, enhanced authentication, and reason codes, giving developers greater flexibility and control over client interactions.
+Yes. TBMQ supports MQTT over WebSocket and Secure WebSocket (WSS), allowing browser-based applications and web dashboards to publish and subscribe to topics in real time. You can enable the WebSocket endpoints by default on:
+-
+
- 8084 – MQTT over WebSocket +
- 8085 – MQTT over Secure WebSocket (WSS) +
WebSocket support makes it easy to integrate MQTT communication into modern web applications and IoT portals.
+TBMQ supports Keep Alive and Clean Start according to the MQTT specification.
+-
+
- Keep Alive defines the maximum allowed idle time between messages from the client. If no packets are sent within this interval, the broker considers the connection lost. +
- Clean Start (MQTT 5.0) or Clean Session (MQTT 3.1.1) determines whether the broker should maintain the client’s session state after disconnect. +
These options can be configured on the client side. TBMQ automatically handles session persistence and message queuing based on the chosen settings, ensuring reliable reconnect behavior.
+TBMQ enables seamless communication between MQTT clients, ensuring secure and efficient message exchange. It supports advanced MQTT 5.0 features such as shared subscriptions, enhanced authentication, topic aliasing, and flow control, providing flexibility for IoT applications of any scale. TBMQ is built for performance and scalability — whether you’re running a single instance for testing or a clustered setup serving thousands of clients.
+You can host TBMQ in cloud environments, on-premises setups, or locally on your laptop or PC. For the fastest setup, we recommend using the Docker installation guide. If you plan to deploy TBMQ for production or cluster environments, refer to the Cluster Setup Guide for step-by-step instructions on configuring multi-node deployments using Docker Compose.
+The Community Edition of TBMQ does not include a built-in white-labeling feature. However, it is technically possible to replace the default logo by modifying the source code and rebuilding the platform. This approach requires development experience and familiarity with the TBMQ front-end codebase.
+If you need an easier and fully supported way to customize the interface, consider upgrading to the Professional Edition. It allows you to upload your own logo and favicon, customize login and system pages, and adjust colors and branding palettes — all directly from the web interface, without any code changes.
+ {% endif %} + {% if docsPrefix == "pe/" %} +Yes. In the Professional Edition, all branding and visual identity settings can be configured directly from the White Label page in the user interface — no code changes required. You can fully adapt the platform to your company’s look and feel with just a few clicks:
+-
+
- Replace the default TBMQ logo and favicon with your own corporate visuals. +
- Customize login, dashboard, and system pages to greet users with your brand from the first interaction. +
- Adjust color palettes, accent tones, logo size, and styling options (including CSS tweaks) to match your identity. +
- Preview all changes live before publishing them. +
- Configure custom domains — map your own URL (for example,
portal.company.com) so users access TBMQ through your branded domain.
+
These tools make it easy to deliver a fully branded experience that aligns with your organization’s visual standards.
+ {% endif %} +TBMQ ensures secure message exchange by supporting MQTT over SSL/TLS encryption, preventing unauthorized access and data tampering. It allows creating custom authentication providers for validating client credentials, and supports enhanced authentication (MQTT 5.0) for more flexible security models. You can integrate TBMQ with your existing certificate authority or use username/password-based authentication. These features provide a strong foundation for building secure and reliable IoT communication networks.
+TBMQ supports multiple authentication mechanisms to ensure secure and flexible client validation. The available methods include:
+-
+
- Basic authentication – verifies client ID, username, and password credentials stored in the database. +
- X.509 certificate chain authentication – validates clients using SSL/TLS certificates. +
- Enhanced authentication (MQTT 5.0) – supports SCRAM-based authentication flows defined by the MQTT 5.0 specification. +
- JWT authentication – enables token-based authentication and integration with external identity systems via the TBMQ authentication API. +
These options allow you to choose the best approach depending on your deployment and security requirements.
+TBMQ supports SSL/TLS encryption and client certificate authentication (X.509 certificate chain). To enable this feature:
+-
+
- Provide a valid server certificate and private key in the configuration file. +
- Enable the secure MQTT port (default:
8883).
+ - Configure TBMQ to verify client certificates for mutual authentication using X.509 Certificate Chain credentials. +
This ensures that both the client and server validate each other’s identity before establishing a connection, adding a strong layer of security for IoT and enterprise deployments.
+Yes. TBMQ supports JWT (JSON Web Token)–based authentication through authentication providers. This approach enables clients to connect securely using signed tokens instead of static credentials. JWT support is ideal for dynamic or short-lived sessions where credentials are issued by an external identity service.
+TBMQ automatically detects and logs unauthorized connection attempts. When a client fails authentication, the broker records details such as client ID, IP address, username, and TLS status. This data can be reviewed in the Unauthorized Clients dashboard or queried via API for further analysis.
+TBMQ provides tools to monitor unauthorized clients directly through the web interface or REST API. Administrators can filter, inspect, and delete recorded entries. You can also apply blocking rules to reject future connection attempts from known malicious IP addresses or repeated offenders. This feature helps maintain system integrity and visibility into potential security risks.
+TBMQ manages client subscriptions using a Trie-based data structure, which provides fast and memory-efficient topic lookups. All client subscriptions are consumed from a Kafka topic and stored in memory within the Trie, where each node represents a level in the topic filter hierarchy.
+The Trie structure enables prefix-based matching, allowing TBMQ to quickly identify all clients subscribed to topics that match a published message. When a PUBLISH message is read from Kafka, TBMQ uses the Trie to determine the set of clients with relevant subscriptions and forwards the message to each of them.
+This approach ensures high-performance message routing, as the lookup time depends on the length of the topic rather than the total number of subscriptions. It scales efficiently even in large environments with millions of active subscriptions. While this method slightly increases memory usage due to in-memory storage of the Trie, it provides predictable and low-latency message delivery.
+Yes. TBMQ supports shared subscriptions as defined by the MQTT 5.0 specification. Shared subscriptions allow multiple clients to consume messages from the same topic group in a load-balanced manner. This feature is especially useful for scaling message processing horizontally — for example, distributing telemetry data processing among several backend services.
+TBMQ supports retained messages, which ensure that newly connected subscribers immediately receive the most recent message published on a topic. When a client publishes a retained message, TBMQ stores it and delivers it automatically to any future subscribers of that topic. If a retained message with an empty payload is received, TBMQ clears the retained message for that topic, following the MQTT specification.
+A persistent session stores the client’s subscriptions and undelivered QoS 1/2 messages, allowing message delivery to resume after reconnecting. A non-persistent session (Clean Start = true) is temporary — all subscriptions and queued messages are discarded when the client disconnects. TBMQ fully supports both modes and automatically handles session recovery for persistent clients after reconnecting.
+TBMQ follows the MQTT standard for Last Will and Testament (LWT) messages. When a client connects, it can specify an LWT message that the broker will publish automatically if the client disconnects unexpectedly. This feature helps notify other clients or monitoring systems about abnormal disconnections, improving visibility and reliability in IoT systems.
+TBMQ provides detailed metrics on message throughput, including the number of published, received, and dropped messages. These statistics are available through the built-in monitoring dashboard. Administrators can use these insights to track broker performance and optimize system configuration.
+TBMQ offers horizontal scalability, meaning it can grow seamlessly with your workload. Each broker node in a cluster handles a portion of the load, ensuring balanced message processing and uninterrupted performance. Actual throughput depends on hardware, configuration, and message characteristics (size, QoS level, persistence). Optimized setups can handle millions of simultaneous client connections and millions of messages per second. For detailed metrics and benchmarks, visit the Performance Test Page.
+TBMQ exposes detailed performance metrics through its monitoring dashboard and Prometheus endpoint. You can track key indicators such as:
+-
+
- Number of connected clients +
- Message publish and receive rates +
- Queue sizes and processing latency +
- Redis and Kafka performance +
These metrics can be visualized in Grafana or other observability platforms to gain real-time insights into system health and throughput trends.
+TBMQ implements an internal backpressure management mechanism to maintain stable performance when clients are unable to consume messages quickly. When a client’s network channel becomes non-writable, TBMQ temporarily pauses message delivery for that client. Once the channel becomes writable again, queued messages are delivered in the correct order. This design prevents slow consumers from impacting other clients, ensuring consistent throughput across the cluster.
+TBMQ CE is distributed under the Apache 2.0 License, allowing both personal and commercial usage. You can freely deploy, modify, and distribute it in any environment without additional licensing costs.
+ {% endif %} + {% if docsPrefix == "pe/" %} +TBMQ PE is a commercially licensed version of TBMQ available under a subscription-based license. It includes additional enterprise-grade features, support services, and maintenance. Use of the PE version requires a valid license agreement with ThingsBoard, Inc.
+ {% endif %} +You can access community-driven troubleshooting guides and documentation, or contact us directly for technical assistance. Learn more about services we provide.
+