FoundationDB Cluster

advanced

FoundationDB distributed key-value store.

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.

Key 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

Common Use Cases

1Financial trading platforms requiring strict consistency for order matching and settlement systems
2E-commerce inventory management systems preventing overselling through atomic stock updates
3Multi-tenant SaaS applications needing isolated yet consistent data across customer boundaries
4Real-time analytics platforms requiring consistent reads across distributed data sets
5Gaming backends managing player state, leaderboards, and in-game economies with transaction guarantees
6Supply chain management systems tracking goods movement with audit trail requirements
7Content 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  fdb-coordinator: 
3    image: foundationdb/foundationdb:latest
4    container_name: fdb-coordinator
5    restart: unless-stopped
6    environment: 
7      - FDB_COORDINATOR=fdb-coordinator
8      - FDB_CLUSTER_FILE_CONTENTS=docker:docker@fdb-coordinator:4500
9    volumes: 
10      - fdb_coord_data:/var/fdb/data
11
12  fdb-storage-1: 
13    image: foundationdb/foundationdb:latest
14    container_name: fdb-storage-1
15    restart: unless-stopped
16    environment: 
17      - FDB_COORDINATOR=fdb-coordinator
18      - FDB_CLUSTER_FILE_CONTENTS=docker:docker@fdb-coordinator:4500
19    volumes: 
20      - fdb_storage1_data:/var/fdb/data
21    depends_on: 
22      - fdb-coordinator
23
24  fdb-storage-2: 
25    image: foundationdb/foundationdb:latest
26    container_name: fdb-storage-2
27    restart: unless-stopped
28    environment: 
29      - FDB_COORDINATOR=fdb-coordinator
30      - FDB_CLUSTER_FILE_CONTENTS=docker:docker@fdb-coordinator:4500
31    ports: 
32      - "${FDB_PORT:-4500}:4500"
33    volumes: 
34      - fdb_storage2_data:/var/fdb/data
35    depends_on: 
36      - fdb-coordinator
37
38volumes: 
39  fdb_coord_data: 
40  fdb_storage1_data: 
41  fdb_storage2_data:

.env Template

.env

1# FoundationDB
2FDB_PORT=4500

Usage Notes

1FDB at localhost:4500
2Use fdbcli for management
3ACID compliant distributed DB
4Used by Apple, Snowflake

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

fdb-coordinator

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

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

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  fdb-coordinator:
5    image: foundationdb/foundationdb:latest
6    container_name: fdb-coordinator
7    restart: unless-stopped
8    environment:
9      - FDB_COORDINATOR=fdb-coordinator
10      - FDB_CLUSTER_FILE_CONTENTS=docker:docker@fdb-coordinator:4500
11    volumes:
12      - fdb_coord_data:/var/fdb/data
13
14  fdb-storage-1:
15    image: foundationdb/foundationdb:latest
16    container_name: fdb-storage-1
17    restart: unless-stopped
18    environment:
19      - FDB_COORDINATOR=fdb-coordinator
20      - FDB_CLUSTER_FILE_CONTENTS=docker:docker@fdb-coordinator:4500
21    volumes:
22      - fdb_storage1_data:/var/fdb/data
23    depends_on:
24      - fdb-coordinator
25
26  fdb-storage-2:
27    image: foundationdb/foundationdb:latest
28    container_name: fdb-storage-2
29    restart: unless-stopped
30    environment:
31      - FDB_COORDINATOR=fdb-coordinator
32      - FDB_CLUSTER_FILE_CONTENTS=docker:docker@fdb-coordinator:4500
33    ports:
34      - "${FDB_PORT:-4500}:4500"
35    volumes:
36      - fdb_storage2_data:/var/fdb/data
37    depends_on:
38      - fdb-coordinator
39
40volumes:
41  fdb_coord_data:
42  fdb_storage1_data:
43  fdb_storage2_data:
44EOF
45
46# 2. Create the .env file
47cat > .env << 'EOF'
48# FoundationDB
49FDB_PORT=4500
50EOF
51
52# 3. Start the services
53docker compose up -d
54
55# 4. View logs
56docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/foundationdb-cluster/run | bash

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

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

foundationdb

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download