Installation

Install Embucket using Docker, pre-built binaries, or build from source

Embucket can be installed using multiple methods depending on your environment and requirements. Choose the method that best fits your needs.

System Requirements

Before installing Embucket, ensure your system meets these requirements:

Operating System

• Linux (x86_64, ARM64)
• macOS (Intel, Apple Silicon)
• Windows (via WSL2)

Resources

• Minimum: 512MB RAM, 1 CPU core
• Recommended: 2GB+ RAM, 2+ CPU cores

Embucket is a single binary with zero external dependencies, making it easy to deploy in resource-constrained environments.

Installation Methods

Docker (Recommended)

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

1. Pull the Embucket image

   docker pull embucket/embucket
   
2. Run the container

   Start Embucket with default configuration:

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

   Or run in detached mode:

   docker run --name embucket -d -p 3000:3000 embucket/embucket
   
3. Verify the installation

   Check that the container is running:

   docker ps
   

   You should see the embucket container in the list.

Docker with Custom Configuration

To use a custom configuration file with Docker:

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

This command:

• Mounts your local config directory to /app/config in the container
• Passes the --metastore-config flag to specify the configuration file

For production deployments, use Docker Compose or Kubernetes to manage container lifecycle and configuration. See the Deployment guide.

Pre-built Binary

Download pre-built binaries for your platform from the GitHub Releases page.

1. Download the binary

   Linux (x86_64)

   curl -L -o embucketd https://github.com/Embucket/embucket/releases/latest/download/embucketd-linux-x86_64
   chmod +x embucketd
   
2. Move to system path (optional)

   For easier access, move the binary to a directory in your PATH:

   sudo mv embucketd /usr/local/bin/
   
3. Run Embucket

   Start the Embucket server:

   ./embucketd
   

   Or if you moved it to your PATH:

   embucketd
   

   By default, Embucket listens on port 3000.

Binary with Configuration

To run with a custom configuration file:

./embucketd --metastore-config config/metastore.yaml

The binary includes an embedded metastore for quick starts. For production deployments, use external catalog configuration.

Build from Source

For development or customization, build Embucket from source.

1. Install prerequisites

   Ensure you have the following installed:

   • Rust toolchain (1.70 or later): Install from rustup.rs
   • CMake: Required for some dependencies
   • pkg-config: Required on Linux
   • OpenSSL development libraries: Required on Linux

   Ubuntu/Debian

   sudo apt-get update
   sudo apt-get install -y cmake pkg-config libssl-dev ca-certificates
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   
2. Clone the repository

   git clone https://github.com/Embucket/embucket.git
   cd embucket
   
3. Build the project

   Build in debug mode (faster compile, slower runtime):

   cargo build
   

   Or build in release mode (optimized for performance):

   cargo build --release
   

   Release builds take longer to compile but run significantly faster. Use release mode for production deployments.

4. Run the binary

   For debug builds:

   ./target/debug/embucketd
   

   For release builds:

   ./target/release/embucketd
   

Build Options

Embucket supports optional features during compilation:

# Build without experimental features
cargo build --release --no-default-features

# Build with experimental features enabled
cargo build --release --features experimental

Experimental features may be unstable and are not recommended for production use.

Installation Verification

After installing Embucket using any method, verify the installation:

1. Check the server is running

   If running via Docker:

   docker ps | grep embucket
   

   If running as a binary, check the process:

   ps aux | grep embucketd
   
2. Test the HTTP endpoint

   Verify the server responds to HTTP requests:

   curl http://localhost:3000/health
   

   If the health endpoint is not available, the server is running if you see log output without errors.

3. Connect with Snowflake CLI

   Install and configure the Snowflake CLI to verify connectivity:

   pip install snowflake-cli
   snow connection test -c local
   

   See the Quickstart guide for detailed CLI setup instructions.

Environment Variables

Embucket can be configured using environment variables:

Variable	Description	Default
METASTORE_CONFIG	Path to metastore configuration file	-
JWT_SECRET	Secret key for JWT token generation	63f4945d921d599f27ae4fdf5bada3f1
TRACING_LEVEL	Logging level (trace, debug, info, warn, error)	info
RUST_LOG	Rust logging configuration	info
OBJECT_STORE_BACKEND	Object storage backend (file, s3, gcs, azure)	file
FILE_STORAGE_PATH	Local file storage path	data/
BUCKET_HOST	Host address to bind to	0.0.0.0

Using Environment Variables

Docker

docker run --name embucket --rm -p 3000:3000 \
  -e TRACING_LEVEL=debug \
  -e JWT_SECRET=your-secret-key \
  embucket/embucket

For production deployments, always use a strong, randomly generated JWT_SECRET. The default value is only suitable for development.

Troubleshooting

Docker Issues

Problem: Cannot connect to the Docker daemon

Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Solution: Ensure Docker is running:

# Linux
sudo systemctl start docker

# macOS
open -a Docker

---

Problem: Port 3000 is already in use

Error starting userland proxy: listen tcp4 0.0.0.0:3000: bind: address already in use

Solution: Use a different port:

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

Then connect to localhost:8080 instead.

Build Issues

Problem: Cargo build fails with linker errors

error: linking with `cc` failed

Solution: Install required development dependencies:

Ubuntu/Debian

sudo apt-get install -y build-essential cmake pkg-config libssl-dev

---

Problem: Out of memory during compilation

error: could not compile due to previous error
Signal: 9 (SIGKILL)

Solution: Reduce parallel compilation jobs:

cargo build --release -j 1

Runtime Issues

Problem: Permission denied when running the binary

bash: ./embucketd: Permission denied

Solution: Make the binary executable:

chmod +x embucketd

---

Problem: Server starts but cannot connect from Snowflake CLI

Solution: Check that:

1. The server is listening on the correct host:

   export BUCKET_HOST=0.0.0.0
   ./embucketd
   

2. Firewall allows connections to port 3000

3. Snowflake CLI configuration uses http:// protocol (not https://)

Next Steps

Now that you have Embucket installed, continue with:

Quickstart

Run your first queries in under 5 minutes

Configuration

Configure external catalogs and data sources

Deployment

Deploy Embucket to production environments

SQL Reference

Learn about Snowflake SQL support