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 (relaxed security, in-memory storage)
./rustberg --dev --insecure-http

# Output:
# ⚠️  Running in DEVELOPMENT mode - security requirements relaxed
# ⚠️  CORS allows all origins ("*")
# 🚀 Rustberg listening on http://127.0.0.1:8000

The --dev flag relaxes security checks (allows wildcard CORS, self-signed TLS). Without --dev, Rustberg runs in production mode which requires explicit CORS origins.

Development mode is NOT suitable for production. Use proper configuration for production deployments.

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
RUSTBERG_DEV Enable development mode false
RUSTBERG_NO_AUTH Disable authentication (dev only) false

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