# FoundationDB Cluster

> FoundationDB distributed key-value store.

- Category: Database Stacks
- Difficulty: advanced
- Components: foundationdb
- Tags: foundationdb, distributed, key-value, cluster
- Source: https://docker.recipes/databases/foundationdb-cluster

## Overview

FoundationDB is an open-source, distributed database originally developed by Apple that combines NoSQL scalability with ACID transactions. Acquired by Apple in 2015 and later open-sourced, FoundationDB provides a unique key-value interface with full ACID guarantees across the entire cluster, making it one of the few distributed databases to achieve true consistency without sacrificing availability. The database uses a sophisticated architecture with separate transaction and storage systems, allowing it to handle millions of operations per second while maintaining strict consistency guarantees.

This FoundationDB cluster configuration establishes a three-node setup with one coordinator node and two storage nodes, creating a fault-tolerant distributed system. The coordinator serves as the cluster controller, managing metadata and coordinating transactions, while the storage nodes handle data persistence and retrieval. All nodes communicate through FoundationDB's custom wire protocol on port 4500, with the cluster file enabling automatic discovery and configuration sharing across the distributed system.

This configuration is ideal for developers and organizations requiring distributed database capabilities with strong consistency guarantees, particularly those building financial systems, inventory management platforms, or applications where data integrity is paramount. Companies like Snowflake rely on FoundationDB for their core infrastructure, and this Docker setup provides an accessible way to evaluate and deploy FoundationDB's enterprise-grade capabilities without complex manual cluster configuration.

## Features

- Multi-version concurrency control with serializable snapshot isolation for true ACID transactions
- Automatic data distribution and rebalancing across storage nodes with configurable replication factors
- Separated transaction system from storage layer enabling independent scaling of compute and storage
- Self-healing cluster architecture with automatic failure detection and recovery
- Deterministic simulation testing ensuring database correctness under various failure scenarios
- Layered architecture allowing custom data models and indexes to be built on top of the key-value interface
- Sub-second failover times with automatic coordinator election during node failures
- Built-in backup and restore capabilities with point-in-time recovery support

## Use cases

- Financial trading platforms requiring strict consistency for order matching and settlement systems
- E-commerce inventory management systems preventing overselling through atomic stock updates
- Multi-tenant SaaS applications needing isolated yet consistent data across customer boundaries
- Real-time analytics platforms requiring consistent reads across distributed data sets
- Gaming backends managing player state, leaderboards, and in-game economies with transaction guarantees
- Supply chain management systems tracking goods movement with audit trail requirements
- Content management systems requiring consistent metadata and file references across distributed storage

## Prerequisites

- Minimum 4GB RAM allocated to Docker (FoundationDB coordinator requires 2GB, each storage node needs 1GB)
- At least 10GB available disk space for persistent data volumes across three nodes
- Port 4500 available on host system for FoundationDB client connections
- Understanding of distributed systems concepts and ACID transaction principles
- Familiarity with fdbcli command-line interface for cluster management and monitoring
- Docker Compose version 3.8 or higher for proper volume and dependency management

## docker-compose.yml

```yaml
services:
  fdb-coordinator:
    image: foundationdb/foundationdb:latest
    container_name: fdb-coordinator
    restart: unless-stopped
    environment:
      - FDB_COORDINATOR=fdb-coordinator
      - FDB_CLUSTER_FILE_CONTENTS=docker:docker@fdb-coordinator:4500
    volumes:
      - fdb_coord_data:/var/fdb/data

  fdb-storage-1:
    image: foundationdb/foundationdb:latest
    container_name: fdb-storage-1
    restart: unless-stopped
    environment:
      - FDB_COORDINATOR=fdb-coordinator
      - FDB_CLUSTER_FILE_CONTENTS=docker:docker@fdb-coordinator:4500
    volumes:
      - fdb_storage1_data:/var/fdb/data
    depends_on:
      - fdb-coordinator

  fdb-storage-2:
    image: foundationdb/foundationdb:latest
    container_name: fdb-storage-2
    restart: unless-stopped
    environment:
      - FDB_COORDINATOR=fdb-coordinator
      - FDB_CLUSTER_FILE_CONTENTS=docker:docker@fdb-coordinator:4500
    ports:
      - "${FDB_PORT:-4500}:4500"
    volumes:
      - fdb_storage2_data:/var/fdb/data
    depends_on:
      - fdb-coordinator

volumes:
  fdb_coord_data:
  fdb_storage1_data:
  fdb_storage2_data:
```

## .env

```bash
# FoundationDB
FDB_PORT=4500
```

## Usage notes

- FDB at localhost:4500
- Use fdbcli for management
- ACID compliant distributed DB
- Used by Apple, Snowflake

## Troubleshooting

- Cluster status shows 'database unavailable': Verify all three containers are running and coordinator is accessible on port 4500
- Storage nodes fail to join cluster: Check FDB_CLUSTER_FILE_CONTENTS environment variable matches across all services
- Transaction timeouts or conflicts: Monitor cluster load with fdbcli and consider adjusting transaction retry logic in applications
- Data directory permission errors: Ensure /var/fdb/data directory has proper write permissions within containers
- Coordinator election failures: Verify coordinator service starts first using depends_on configuration and check network connectivity
- High memory usage warnings: Increase Docker memory limits as FoundationDB aggressively caches data for performance

