Skip to main content
For production, run Firebolt on Kubernetes with the Firebolt Operator or the Helm chart. They handle node startup, health checks, upgrades, and metadata for you. Run the raw binaries only when you cannot use Kubernetes or Docker, or for local testing.
This guide runs Firebolt directly from binaries, with no Docker and no Kubernetes:
  • firebolt, the database binary that executes queries. It bundles the planner, runtime, and storage engine.
  • dedicated-pensieve, an optional standalone metadata service, for running multiple independent Firebolt clusters with decoupled metadata.

​
Concepts

An Engine is a cluster of one or more nodes that execute queries together. Every node runs the same firebolt binary and is given its position with --node. A query submitted to any node is planned there and its stages are distributed across that Engine’s nodes. These pages assume one node per machine: one firebolt process on its own host, reached at that host’s address. That is the only model a real deployment should use. You can also place several nodes on a single machine, but only for testing, and it needs extra care to avoid port collisions. That case is covered separately in Colocate multiple nodes on one host. Table data lives in object storage (S3, GCS, or Azure Blob Storage) as immutable tablets. Nodes read tablets directly from object storage and cache them on local SSD, so adding a node adds compute without moving data. The directory you pass with --data-dir holds only this cache and the node’s configuration; object storage is the single source of truth. Metadata, the catalog of tables, columns, and tablet locations, is served in one of two modes, set by instance.type in the engine configuration:
  • Embedded metadata (the default): the Engine hosts its own metadata service, backed by a local SQLite database. No separate process and no Postgres. The metadata belongs to that one Engine and cannot be shared. This is the simplest deployment.
  • Standalone metadata: the Engine connects to a separate dedicated-pensieve process backed by Postgres. Because the metadata lives outside any single Engine, several Engines can share one catalog and one bucket, and each reads the latest snapshot written by the others. This is the basis of workload isolation: two Engines operate on the same tablets without drawing compute from each other.
Run one firebolt node per machine. Every node reads and writes the same object storage bucket. The metadata mode decides whether there is a separate process.
Node 0 hosts the embedded metadata in a local SQLite database. No separate process and no Postgres.

​
Choose a deployment

​
How the nodes communicate

A node serves clients over HTTP, exchanges work with its peers over two channels, reaches the metadata service over gRPC, and reads and writes tablets directly to object storage. Each port below is per node. The engine binds them on all interfaces (0.0.0.0) by default, so with one node per machine the defaults never collide and you do not have to change them. The metadata service uses one more port, depending on the mode: Across machines, the firewall must allow the node-to-node ports between Engine nodes, the metadata port from every node to the metadata host, and Postgres from the standalone metadata host to its database. Use the address each node’s peers reach it on, not localhost. All nodes of one Engine must start concurrently. Each node’s readiness check runs a distributed query that needs its peers reachable, so starting one node and waiting for it before starting the next deadlocks. Start every node of an Engine, then poll each node’s /ping until all return Ok.. Stop a node by sending SIGTERM to the process ID that firebolt server start prints (or that you captured when launching it in the background).

​
Get the binaries

Put these binaries on your PATH:
  • firebolt, the engine.
  • dedicated-pensieve, the standalone metadata service (only needed for standalone metadata).
If Firebolt provides prebuilt standalone archives for your environment, extract each archive and move the binary onto your PATH. Otherwise, build the binaries yourself. The examples in this guide invoke them as firebolt and dedicated-pensieve. The firebolt binary bundles the server and a CLI; every mode here starts a server with firebolt server start. See engine arguments for --data-dir and --server-config, and engine configuration for the YAML file.

​
Build the binaries yourself

Build on Ubuntu 22.04 or newer. Clone the repository and its submodules, configure once, then build both targets:
The binaries are written to build/programs/firebolt/firebolt and build/programs/dedicated-pensieve/dedicated-pensieve. Add both directories to your PATH (or substitute the full path in each command):