Docker Deployment

Run Embucket using Docker for simplified deployment

Quick Start

The fastest way to get started with Embucket is using Docker:

docker run --name embucket --rm -p 3000:3000 embucket/embucket

This command starts Embucket and exposes the Snowflake-compatible API on port 3000.

Docker Run Command

Basic Usage

Run Embucket with default configuration:

docker run --name embucket --rm -p 3000:3000 embucket/embucket

With Configuration File

Mount a configuration file to connect to external catalogs:

docker run --name embucket --rm -p 3000:3000 \
  -v $PWD/config:/app/config \
  embucket/embucket \
  ./embucketd --metastore-config config/metastore.yaml

Custom Port Mapping

Embucket exposes two ports:

• 3000: Snowflake-compatible API (default)
• 8080: Additional API port

docker run --name embucket --rm \
  -p 3000:3000 \
  -p 8080:8080 \
  embucket/embucket

Docker Compose

For production deployments with dependencies, use Docker Compose. Here’s an example with MinIO for object storage:

services:
  embucket:
    image: embucket/embucket
    container_name: embucket
    depends_on:
      - minio
    ports:
      - 3000:3000
      - 8080:8080
    environment:
      - API_URL=http://localhost:3000
      - OBJECT_STORE_BACKEND=s3
      - SLATEDB_PREFIX=data/
      - AWS_ACCESS_KEY_ID=minioadmin
      - AWS_SECRET_ACCESS_KEY=minioadmin
      - AWS_REGION=us-east-2
      - S3_BUCKET=mybucket
      - S3_ENDPOINT=http://warehouse.minio:9000
      - S3_ALLOW_HTTP=true
      - CATALOG_URL=http://embucket:3000/catalog
    volumes:
      - ./tmp:/tmp

  minio:
    image: minio/minio
    container_name: minio
    environment:
      - MINIO_ROOT_USER=minioadmin
      - MINIO_ROOT_PASSWORD=minioadmin
    volumes:
      - ./warehouse:/warehouse
    ports:
      - 9001:9001
      - 9000:9000
    command: ["server", "/warehouse", "--console-address", ":9001"]

Start the stack:

docker compose up -d

Environment Variables

Object Storage Configuration

OBJECT_STORE_BACKEND · string · default: "file"

Object storage backend type. Options: file, s3

FILE_STORAGE_PATH · string · default: "data/"

Path for file-based storage

S3_BUCKET · string

S3 bucket name when using S3 backend

S3_ENDPOINT · string

S3 endpoint URL (for MinIO or custom S3-compatible storage)

S3_ALLOW_HTTP · boolean · default: "false"

Allow HTTP connections to S3 (useful for local MinIO)

AWS Credentials

AWS_ACCESS_KEY_ID · string

AWS access key ID for S3 access

AWS_SECRET_ACCESS_KEY · string

AWS secret access key for S3 access

AWS_REGION · string · default: "us-east-2"

AWS region for S3 operations

Server Configuration

BUCKET_HOST · string · default: "0.0.0.0"

Host address to bind to (0.0.0.0 in Docker)

API_URL · string

Public API URL for external access

CATALOG_URL · string

Iceberg REST catalog URL

JWT_SECRET · string

JWT secret for authentication (change in production)

Volume Mounts

Configuration Files

Mount your metastore configuration:

docker run --name embucket --rm -p 3000:3000 \
  -v $PWD/config:/app/config \
  embucket/embucket \
  ./embucketd --metastore-config config/metastore.yaml

Data Persistence

For persistent data storage:

docker run --name embucket --rm -p 3000:3000 \
  -v embucket-data:/app/data \
  embucket/embucket

Temporary Files

Mount a directory for temporary query processing:

docker run --name embucket --rm -p 3000:3000 \
  -v ./tmp:/tmp \
  embucket/embucket

Production Considerations

Resource Limits

Set memory and CPU limits for production workloads:

docker run --name embucket --rm \
  -p 3000:3000 \
  --memory="4g" \
  --cpus="2" \
  embucket/embucket

Health Checks

Configure health checks in docker-compose.yml:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 10s
  retries: 3

Logging

Configure logging drivers:

docker run --name embucket --rm \
  --log-driver=json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  embucket/embucket

Security

Run as non-root user (default in Embucket):

• Uses distroless base image
• Runs as nonroot:nonroot user
• Change JWT_SECRET in production

Building Custom Image

To build your own Embucket Docker image:

git clone https://github.com/Embucket/embucket.git
cd embucket
docker build -t my-embucket .

Build Arguments

ENABLE_EXPERIMENTAL · boolean · default: "false"

Enable experimental features during build

docker build \
  --build-arg ENABLE_EXPERIMENTAL=true \
  -t my-embucket .

Next Steps

Configuration

Learn about all configuration options

AWS Lambda

Deploy Embucket as a serverless function