Getting Started

Get Rustberg running in under 5 minutes.

Table of contents

  1. Prerequisites
  2. Installation
    1. Pre-built Binaries (Recommended)
    2. Docker
    3. Helm Chart (Kubernetes)
    4. From Source (Development)
  3. Quick Start
    1. 1. Start the Server
    2. 2. Test the Connection
    3. 3. Create a Namespace
  4. Production Deployment
    1. Single-Node (Persistent Storage)
    2. Kubernetes (S3 Backend)
  5. Configuration
    1. Environment Variables
    2. TOML Configuration
  6. Client Integration
    1. PyIceberg
    2. Spark
    3. Trino
  7. Next Steps
  8. Troubleshooting
  9. Getting Help

Prerequisites

  • Rust 1.89+ (for building from source)
  • Docker (optional, for integration testing)

Installation

Download the latest release for your platform:

# Linux (x86_64)
curl -L https://github.com/hupe1980/rustberg/releases/latest/download/rustberg-linux-x86_64 -o rustberg

# Linux (ARM64)
curl -L https://github.com/hupe1980/rustberg/releases/latest/download/rustberg-linux-aarch64 -o rustberg

# macOS (Apple Silicon)
curl -L https://github.com/hupe1980/rustberg/releases/latest/download/rustberg-darwin-aarch64 -o rustberg

# Windows (x86_64)
curl -L https://github.com/hupe1980/rustberg/releases/latest/download/rustberg-windows-x86_64.exe -o rustberg.exe

# Make executable (Linux/macOS)
chmod +x rustberg

Docker 

docker pull ghcr.io/hupe1980/rustberg:latest
docker run -d -p 8181:8181 --name rustberg ghcr.io/hupe1980/rustberg:latest

Helm Chart (Kubernetes) 

# Clone and install
git clone https://github.com/hupe1980/rustberg
helm install rustberg rustberg/charts/rustberg

# With S3 backend
helm install rustberg charts/rustberg \
  --set rustberg.storage.type=s3 \
  --set rustberg.storage.s3.bucket=my-catalog-bucket

See Kubernetes documentation for full configuration options.

From Source (Development) 

# Clone repository
git clone https://github.com/hupe1980/rustberg.git
cd rustberg

# Build release binary
cargo build --release --all-features

# Binary location
./target/release/rustberg --version

Quick Start

1. Start the Server 

# Development mode (in-memory, auto-generated API key)
./rustberg

# Output:
# ⚠️  DEMO MODE: Using auto-generated API key
# Demo API Key: rustberg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 🚀 Rustberg listening on https://127.0.0.1:8181

Demo mode generates a new API key on each restart. For production, use persistent storage.

2. Test the Connection 

# Get catalog configuration
curl -H "Authorization: Bearer rustberg_xxxxx" \
     http://localhost:8181/v1/config

# Expected response:
# {"defaults":{},"overrides":{}}

3. Create a Namespace 

curl -X POST http://localhost:8181/v1/namespaces \
     -H "Authorization: Bearer rustberg_xxxxx" \
     -H "Content-Type: application/json" \
     -d '{"namespace": ["analytics"], "properties": {}}'

Production Deployment

Single-Node (Persistent Storage) 

# Create data directory
mkdir -p /var/lib/rustberg

# Start with file:// backend
./rustberg \
    --storage file:///var/lib/rustberg \
    --host 0.0.0.0 \
    --port 8181

# Or use a config file
./rustberg --config /etc/rustberg/config.toml

Kubernetes (S3 Backend) 

apiVersion: apps/v1
kind: Deployment
metadata:
  name: rustberg
spec:
  replicas: 3
  selector:
    matchLabels:
      app: rustberg
  template:
    metadata:
      labels:
        app: rustberg
    spec:
      containers:
      - name: rustberg
        image: ghcr.io/hupe1980/rustberg:latest
        ports:
        - containerPort: 8181
        env:
        - name: RUSTBERG_STORAGE
          value: "s3://my-bucket/rustberg-catalog"
        - name: AWS_REGION
          value: "us-east-1"
        resources:
          requests:
            memory: "32Mi"
            cpu: "100m"
          limits:
            memory: "128Mi"
            cpu: "500m"

Configuration

Environment Variables

Variable Description Default
RUSTBERG_HOST Bind address 127.0.0.1
RUSTBERG_PORT Listen port 8181
RUSTBERG_STORAGE Storage backend URL memory://
RUSTBERG_LOG_LEVEL Log verbosity info
RUSTBERG_MASTER_KEY Encryption key (base64) None

TOML Configuration 

# /etc/rustberg/config.toml

[server]
host = "0.0.0.0"
port = 8181
request_timeout_secs = 30

[storage]
object_store_url = "s3://my-bucket/rustberg-catalog"
aws_region = "us-east-1"

[auth]
require_authentication = true
api_key_prefix = "rustberg_"

[rate_limit]
requests_per_second = 100
burst_size = 200

[logging]
level = "info"
format = "json"

Client Integration

PyIceberg 

from pyiceberg.catalog import load_catalog

catalog = load_catalog(
    "rustberg",
    **{
        "uri": "http://localhost:8181",
        "credential": "rustberg_your_api_key_here",
    }
)

# List namespaces
namespaces = catalog.list_namespaces()
print(namespaces)

# Create table
from pyiceberg.schema import Schema
from pyiceberg.types import NestedField, StringType, LongType

schema = Schema(
    NestedField(1, "id", LongType(), required=True),
    NestedField(2, "name", StringType(), required=False),
)

table = catalog.create_table(
    "analytics.users",
    schema=schema,
    location="s3://my-data/users",
)

Spark 

spark.conf.set("spark.sql.catalog.rustberg", "org.apache.iceberg.spark.SparkCatalog")
spark.conf.set("spark.sql.catalog.rustberg.type", "rest")
spark.conf.set("spark.sql.catalog.rustberg.uri", "http://localhost:8181")
spark.conf.set("spark.sql.catalog.rustberg.credential", "rustberg_your_api_key")

// Use the catalog
spark.sql("USE rustberg")
spark.sql("CREATE NAMESPACE analytics")
spark.sql("CREATE TABLE analytics.events (id LONG, event STRING) USING iceberg")

Trino 

# catalog/rustberg.properties
connector.name=iceberg
iceberg.catalog.type=rest
iceberg.rest-catalog.uri=http://rustberg:8181
iceberg.rest-catalog.security=OAUTH2
iceberg.rest-catalog.oauth2.credential=rustberg_your_api_key

-- Query tables
SELECT * FROM rustberg.analytics.events LIMIT 10;

Next Steps

Troubleshooting

Having issues? See the Troubleshooting Guide for solutions to common problems.

Getting Help