$docker.recipes

YugabyteDB Cluster

advanced

YugabyteDB distributed PostgreSQL-compatible database.

[i]Overview

YugabyteDB is a high-performance, cloud-native distributed SQL database that combines the best of traditional RDBMS and NoSQL systems. Built from the ground up to be geo-distributed, YugabyteDB offers PostgreSQL compatibility with automatic sharding, replication, and multi-region capabilities. Originally developed by former Facebook engineers who worked on HBase and Cassandra, YugabyteDB addresses the limitations of traditional databases in cloud-native environments by providing horizontal scalability without sacrificing ACID transactions or SQL capabilities. This Docker configuration deploys a minimal YugabyteDB cluster consisting of one master server (yb-master) and one tablet server (yb-tserver). The master server handles cluster metadata, load balancing, and administrative operations, while the tablet server stores actual data and serves client requests. This architecture allows YugabyteDB to provide both PostgreSQL (YSQL) and Cassandra (YCQL) APIs simultaneously, enabling applications to use familiar SQL operations while benefiting from distributed database capabilities. This setup is ideal for developers and database administrators who need to evaluate distributed PostgreSQL capabilities or prototype applications requiring horizontal scalability. While this single-node cluster configuration doesn't demonstrate YugabyteDB's full distributed capabilities, it provides an excellent foundation for understanding the system's dual API support and can be easily expanded to multi-node deployments for production workloads requiring high availability and geographic distribution.

[*]Key Features

  • [+]PostgreSQL-compatible SQL API (YSQL) on port 5433 with full ACID transactions
  • [+]Cassandra Query Language API (YCQL) on port 9042 for NoSQL workloads
  • [+]Built-in web-based Master UI for cluster monitoring and administration
  • [+]Tablet Server UI providing real-time metrics and query performance insights
  • [+]Automatic data sharding and replication without application changes
  • [+]Multi-version concurrency control with snapshot isolation
  • [+]Support for distributed ACID transactions across multiple tablets
  • [+]Native JSON and JSONB data types with advanced indexing capabilities

[#]Common Use Cases

  • [1]Migrating from PostgreSQL while maintaining compatibility and adding horizontal scalability
  • [2]Building cloud-native applications requiring multi-region data distribution
  • [3]Developing microservices architectures with both SQL and NoSQL data access patterns
  • [4]Creating financial applications requiring distributed ACID transactions
  • [5]Prototyping IoT platforms with high-throughput ingestion and complex analytics
  • [6]Building e-commerce platforms requiring global data consistency and low latency
  • [7]Evaluating distributed SQL databases for enterprise modernization projects

[!]Prerequisites

  • [!]Docker Engine 20.10+ with at least 4GB RAM allocated to containers
  • [!]Minimum 8GB system RAM for optimal YugabyteDB performance
  • [!]Available ports 5433, 7000, 7100, 9000, 9042, and 9100
  • [!]Understanding of PostgreSQL concepts and SQL query optimization
  • [!]Basic knowledge of distributed systems and CAP theorem principles
  • [!]Familiarity with Docker volumes for persistent data storage management
[!]

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

[$]docker-compose.yml

[docker-compose.yml]
1services: 
2  yb-master: 
3    image: yugabytedb/yugabyte:latest
4    container_name: yb-master
5    restart: unless-stopped
6    command: bash -c "
7      /home/yugabyte/bin/yb-master
8      --fs_data_dirs=/mnt/disk0
9      --master_addresses=yb-master: 7100
10      --rpc_bind_addresses=yb-master: 7100
11      "
12    ports: 
13      - "${MASTER_UI_PORT:-7000}:7000"
14    volumes: 
15      - yb_master_data:/mnt/disk0
16
17  yb-tserver: 
18    image: yugabytedb/yugabyte:latest
19    container_name: yb-tserver
20    restart: unless-stopped
21    command: bash -c "
22      /home/yugabyte/bin/yb-tserver
23      --fs_data_dirs=/mnt/disk0
24      --tserver_master_addrs=yb-master: 7100
25      --rpc_bind_addresses=yb-tserver: 9100
26      "
27    ports: 
28      - "${YSQL_PORT:-5433}:5433"
29      - "${YCQL_PORT:-9042}:9042"
30      - "${TSERVER_UI_PORT:-9000}:9000"
31    volumes: 
32      - yb_tserver_data:/mnt/disk0
33    depends_on: 
34      - yb-master
35
36volumes: 
37  yb_master_data: 
38  yb_tserver_data:

[$].env Template

[.env]
1# YugabyteDB
2MASTER_UI_PORT=7000
3YSQL_PORT=5433
4YCQL_PORT=9042
5TSERVER_UI_PORT=9000

[i]Usage Notes

  1. [1]Master UI at http://localhost:7000
  2. [2]PostgreSQL at localhost:5433
  3. [3]Cassandra at localhost:9042
  4. [4]Distributed PostgreSQL

Individual Services(2 services)

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

yb-master
yb-master:
  image: yugabytedb/yugabyte:latest
  container_name: yb-master
  restart: unless-stopped
  command: bash -c " /home/yugabyte/bin/yb-master --fs_data_dirs=/mnt/disk0 --master_addresses=yb-master:7100 --rpc_bind_addresses=yb-master:7100 "
  ports:
    - ${MASTER_UI_PORT:-7000}:7000
  volumes:
    - yb_master_data:/mnt/disk0
yb-tserver
yb-tserver:
  image: yugabytedb/yugabyte:latest
  container_name: yb-tserver
  restart: unless-stopped
  command: bash -c " /home/yugabyte/bin/yb-tserver --fs_data_dirs=/mnt/disk0 --tserver_master_addrs=yb-master:7100 --rpc_bind_addresses=yb-tserver:9100 "
  ports:
    - ${YSQL_PORT:-5433}:5433
    - ${YCQL_PORT:-9042}:9042
    - ${TSERVER_UI_PORT:-9000}:9000
  volumes:
    - yb_tserver_data:/mnt/disk0
  depends_on:
    - yb-master

[>]Quick Start

[terminal]
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  yb-master:
5    image: yugabytedb/yugabyte:latest
6    container_name: yb-master
7    restart: unless-stopped
8    command: bash -c "
9      /home/yugabyte/bin/yb-master
10      --fs_data_dirs=/mnt/disk0
11      --master_addresses=yb-master:7100
12      --rpc_bind_addresses=yb-master:7100
13      "
14    ports:
15      - "${MASTER_UI_PORT:-7000}:7000"
16    volumes:
17      - yb_master_data:/mnt/disk0
18
19  yb-tserver:
20    image: yugabytedb/yugabyte:latest
21    container_name: yb-tserver
22    restart: unless-stopped
23    command: bash -c "
24      /home/yugabyte/bin/yb-tserver
25      --fs_data_dirs=/mnt/disk0
26      --tserver_master_addrs=yb-master:7100
27      --rpc_bind_addresses=yb-tserver:9100
28      "
29    ports:
30      - "${YSQL_PORT:-5433}:5433"
31      - "${YCQL_PORT:-9042}:9042"
32      - "${TSERVER_UI_PORT:-9000}:9000"
33    volumes:
34      - yb_tserver_data:/mnt/disk0
35    depends_on:
36      - yb-master
37
38volumes:
39  yb_master_data:
40  yb_tserver_data:
41EOF
42
43# 2. Create the .env file
44cat > .env << 'EOF'
45# YugabyteDB
46MASTER_UI_PORT=7000
47YSQL_PORT=5433
48YCQL_PORT=9042
49TSERVER_UI_PORT=9000
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/yugabytedb-cluster/run | bash

[?]Troubleshooting

  • [!]yb-master fails to start with 'address already in use': Check if port 7100 is occupied by another service or previous YugabyteDB instance
  • [!]Connection refused on PostgreSQL port 5433: Wait 60-90 seconds after startup for tablet server initialization to complete
  • [!]Web UI shows 'Under-replicated tablets': Normal behavior in single-node setup, add more tablet servers for proper replication
  • [!]High memory usage warnings in logs: Increase Docker memory limits or reduce yb-tserver cache sizes using --db_block_cache_size_bytes flag
  • [!]YSQL queries timeout or fail: Verify tablet server is healthy via port 9000 UI and check for resource constraints
  • [!]Data persistence issues after container restart: Ensure Docker volumes are properly mounted and have sufficient disk space

Community Notes

Loading...
Loading notes...

## Download Recipe Kit

Get all files in a ready-to-deploy package

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

## Components

yugabytedb

## Tags

#yugabytedb#distributed#postgresql#cluster

## Category

Database Stacks

## Related