Deployment Scenarios

This article describes the most common deployment architectures supported by ThingsBoard. Every deployment scenario has its own pros and cons. Choosing the right architecture for your deployment depends on your cost, performance, and high-availability requirements.

Described below are three reference architectures, ranging from a single standalone server to a high-availability cluster spanning multiple Availability Zones (AZs). Each section lists the minimum compute resources it requires.

Setting up ThingsBoard depends on several factors, including your business needs, compliance rules, and expected growth. This section lays out the technical details to make your architecture decision easier.

Your choice of deployment affects how easily you can install, manage, and grow your system.

This table compares their resilience, scaling model, and minimum compute requirements.

It is important to plan both the amount of data you expect to store (persisted telemetry) and the amount you expect to query (dashboard widgets, API responses). Your database choice strongly influences how much data you can read and write at sustainable performance.

ThingsBoard supports two primary database topologies: SQL-only and Hybrid.

1. SQL-only topology uses PostgreSQL exclusively for storing all ThingsBoard data, including entities and telemetry. This approach simplifies architecture and maintenance, and is best suited for environments with predictable data volume.
2. Hybrid topology uses a Cassandra database for historical time-series (telemetry) data, while PostgreSQL handles entity and latest telemetry data. Deploying a dedicated NoSQL database enables exclusive features, such as per-item telemetry retention, and provides more predictable storage management. This approach is best for environments with continuously growing telemetry and data volume, requiring optimized storage for historical time-series.

There is no universal hard limit on the number of reads or writes a PostgreSQL-only topology can handle, nor is there a specific threshold where a Hybrid approach becomes mandatory. Performance relies heavily on use-case specifics, such as the number of devices, how often and how much telemetry they send, dashboard complexity, and how that data is processed and stored.

However, consider the Hybrid topology if any of the following characteristics match your ThingsBoard environment:

• Long retention periods (one year or more) are required, and older data is frequently queried (dashboards or API calls). Cassandra offers more predictable and efficient long-term storage, especially when the total dataset grows into hundreds of gigabytes.
• Dashboards display complex widgets with multiple time-series on a single page. That is especially relevant for dashboards spanning weeks-long time windows, or using aggregations with a large number of data points and short grouping intervals. ThingsBoard’s telemetry storage model is significantly more optimized for Cassandra when reading old data across wide time ranges.
• Different telemetry types require different retention periods. PostgreSQL supports only global TTL; Cassandra allows per-key or per-row TTL, enabling flexible retention strategies.

Capacity depends on many factors: payload shape, rule-chain processing, query patterns, and how evenly traffic arrives — and each of those may affect the limits of specific application components. That is why the scenario descriptions avoid fixed device or throughput ceilings.

If you’re unsure which scenario fits, you can estimate a recommended starting point from your device workload.

The main metric used throughout this section is data points per second (dp/s) — the number of telemetry values written per second, calculated as follows:

dp/s = devices × messages/min × data points/message ÷ 60

For example, 2,000 devices sending 2 messages per minute with 8 data points each produce ~533 dp/s:

2,000 × 2 × 8 = 32,000 (data points per minute)
32,000 ÷ 60 ≈ 533 dp/s

Note a few other sizing factors that matter as much as raw dp/s:

• Device count matters on its own. The Device State service can handle around 100,000 devices per TB-core/TB-node, so very large fleets lean toward a multi-node setup regardless of dp/s.
• Count connections, not just throughput. A single transport handles roughly 50,000 concurrent direct device connections; beyond that, add more transport replicas, or route devices through a dedicated MQTT broker or Gateway instead of connecting them directly to the transport layer.
• Size for sustained load, not every spike. Traffic rarely arrives evenly, so specific patterns (for example, devices that report on a synchronized schedule) can briefly push dp/s above average. Kafka absorbs these short bursts between transport and the rule engine. You still need to size for the considerations above, as these are exceptions where queue buffering does not apply.
• Size storage for retention, not just throughput. Based on Performance measurements, storage ≈ dp/s × retention days × ~14 MB (PostgreSQL) or ~3 MB (Cassandra). Storage figures in the Minimum requirements tables are a floor for short retention periods.

This deployment scenario is designed for straightforward, cost-efficient deployments supporting applications with low to moderate workloads and a limited need to scale horizontally. It adopts a monolithic server approach, consolidating core services onto a single compute instance to reduce infrastructure complexity and operational effort.

The deployment pattern includes a base setup plus optional add-ons.

For the simplest, most cost-efficient setup, all components, including the database and proxy, are hosted on a single server. This configuration is ideal for prototyping, development environments, or small-scale production workloads where ease of management and cost are the primary concerns.

You can further improve this architecture by applying optional add-ons, described below.

Compute Resources:

• Application server: 4 vCPU, 16 GB RAM

Application Components:

The following services run directly on the host:

Pros:

• Lowest cost deployment option
• Very simple to install, manage, and upgrade
• Minimal operational expertise required

Cons:

• No horizontal scaling
• Single point of failure (entire deployment runs on one server)
• Local PostgreSQL requires manual maintenance and backups
• Not suitable for high-availability or high-throughput scenarios

Minimum requirements:

Recommended CPU architecture: x86-64.

The default Scenario A configuration does not include Kafka. However, Kafka can be added as a supplemental component to handle bursts of telemetry data without overloading the main application, ensuring more reliable message handling.

This configuration separates the application stack from the data storage by moving the database onto an external Postgres instance. This isolates database load from the application and lets you scale and back up storage independently, while keeping the application deployment simple.

Architectural Modifications:

• Entity and telemetry data: migrate from the local PostgreSQL to an external Postgres instance (Postgres node).

Additional Compute Resources:

• Postgres node: 4 vCPU, 4 GB RAM

Scenario A provides the simplest and most cost-efficient deployment path but is best suited for environments with predictable, moderate workloads. While the monolithic design reduces operational overhead, it also introduces clear limitations in scalability and fault tolerance. The external Postgres add-on improves database reliability while keeping the single-node application simple.

This scenario is ideal for early-stage deployments but may require vertical scaling as system demands increase.

This reference targets a horizontally scalable deployment. While ThingsBoard still runs as a single instance (monolith), the overall architecture is fundamentally different from Scenario A. By deploying into a Kubernetes cluster, this setup achieves self-healing and the ability to scale out horizontally when needed.

It is ideal for production environments anticipating future growth beyond initial operational loads. Kubernetes handles container placement, restarts, and configuration rollouts, keeping day-to-day operations low-effort.

The deployment pattern includes two configuration options, each optimized for a different level of data ingestion.

For workloads with moderate data ingestion rates, this setup uses a Postgres instance to store both entity and telemetry data. Public access to the ThingsBoard application inside the cluster is provided by a load balancer.

Compute Resources:

• Kubernetes cluster provisioned with a single worker node
• Node: 4 vCPU, 16 GB RAM

Application Components:

The following containerized services are deployed to the compute node:

Database Specifications:

• Postgres node: 4 vCPU, 4 GB RAM

Pros:

• Easy to back up and maintain PostgreSQL database
• Production-ready deployment
• Ready to scale horizontally
• Self-healing cluster

Cons:

• Additional costs for managed Kubernetes and database services
• Single point of failure (single Availability Zone)

Minimum requirements:

Recommended CPU architecture: ARM64 for application nodes; x86-64 for the Postgres node.

At higher telemetry throughput, the architecture may be transitioned to a hybrid database topology. Switching telemetry writes to Cassandra enables far greater scalability, especially valuable for read-heavy and write-heavy workloads.

Architectural Modifications:

• Entity data: stays on the Postgres node (can now be downsized to a burstable instance if available)
• Telemetry data: migrate from the Postgres node to a self-hosted Apache Cassandra cluster

Additional Compute Resources:

Three additional worker nodes are provisioned to host the distributed Cassandra cluster:

• Cassandra node: 2 vCPU, 8 GB RAM
• Node count: 3
• Deployment pattern: one Cassandra instance per node (ensuring fault tolerance and data replication)

Pros:

• Easy to back up and maintain PostgreSQL database
• Cassandra provides enhanced read/write performance for telemetry data
• Production-ready deployment
• Ready to scale horizontally
• Self-healing cluster

Cons:

• Additional costs for managed Kubernetes and database services
• Single point of failure (single Availability Zone)
• Self-hosted Cassandra adds a layer of backup and maintenance work

Minimum requirements:

Recommended CPU architecture: ARM64 for application nodes; ARM64 for the Postgres node (burstable); x86-64 for Cassandra nodes.

Scenario B offers a significant step up from the previous approach, establishing a production-ready, horizontally scalable environment. This architecture effectively minimizes operational overhead related to infrastructure management.

While this setup is still contained within a single Availability Zone, it provides a self-healing cluster capable of recovering from individual service or node issues.

This scenario is ideal for organizations anticipating future growth and requiring a robust foundation that can scale out effortlessly.

This deployment option is designed for production instances requiring high availability and fault tolerance. Additionally, it runs more replicas of both ThingsBoard and third-party services, so it can handle more load and higher ingestion.

This scenario is a direct upgrade to Scenario B, featuring multiple replicas spread across different Availability Zones. Like its preceding scenario, it runs on Kubernetes, which automates container placement, restarts, and configuration rollouts. There are two distinct configurations optimized for different ingestion rates.

For workloads with moderate data ingestion rates, this setup uses a Postgres instance to store both entity and telemetry data. Public access to the ThingsBoard application inside the cluster is provided by a load balancer.

Compute Resources:

• Kubernetes cluster provisioned across three Availability Zones
  • each of the three worker nodes is deployed in its own Availability Zone
• Node: 4 vCPU, 16 GB RAM

Application Components:

The following containerized services are deployed across all compute nodes. Each service should use anti-affinity rules to ensure its replicas are spread evenly across Availability Zones:

Database Specifications:

• Postgres node: 4 vCPU, 4 GB RAM
• A Postgres replica in a separate Availability Zone with automatic failover, for example a managed Multi-AZ deployment (two Postgres nodes total)

Pros:

• Easy to back up and maintain PostgreSQL database
• Self-healing cluster
• Multi-replica deployment that satisfies strict availability requirements
• Scaled services naturally provide significantly improved performance

Cons:

• Extra costs for managing more Kubernetes and database services

Minimum requirements:

Recommended CPU architecture: ARM64 for application nodes; x86-64 for the Postgres node and replica.

As in Scenario B, the second configuration option transitions to a hybrid database topology. Switching telemetry writes to Cassandra enables far greater scalability, especially valuable for read-heavy and write-heavy workloads.

Architectural Modifications:

• Entity data: stays on the Postgres node (can now be downsized to a burstable instance if available)
• Telemetry data: migrate from the Postgres node to a self-hosted Apache Cassandra cluster

Additional Compute Resources:

Three additional worker nodes are provisioned to host the distributed Cassandra cluster:

• Cassandra node: 2 vCPU, 8 GB RAM
• Node count: 3
• Deployment pattern: one Cassandra instance per node (ensuring fault tolerance and data replication)

Pros:

• Easy to back up and maintain PostgreSQL database
• Cassandra provides enhanced read/write performance for telemetry data
• Self-healing cluster
• Multi-replica deployment that satisfies strict availability requirements
• Scaled services naturally provide maximum performance

Cons:

• Extra costs for managing more Kubernetes and database services
• Self-hosted Cassandra adds a layer of backup and maintenance work

Minimum requirements:

Recommended CPU architecture: ARM64 for application nodes; ARM64 for the Postgres node and replica (burstable); x86-64 for Cassandra nodes.

Scenario C is the definitive choice for production deployments that have strict high availability and fault tolerance requirements. As a direct evolution of Scenario B, this architecture expands its benefits by spanning all critical services, including the worker nodes and the database, across multiple Availability Zones.

The deployment of multiple replicas with anti-affinity rules ensures that the application remains fully operational even during a catastrophic failure of an entire AZ. This multi-AZ scaling simultaneously delivers significantly improved performance and resilience by distributing load across more resources.

This scenario is ideal for mission-critical applications where uptime and performance under high load are paramount.

• Performance — benchmark results behind the dp/s figures: throughput, CPU, IOPS, and storage measured per database and queue setup.
• Installation — deployment guides for your chosen scenario: standalone for Scenario A, or a Kubernetes cluster for Scenarios B and C.