Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quickstart: Run the Server

This guide will get the Fluree server running on your machine in minutes.

Installation

The macOS builds are for Apple silicon and need macOS 14 (Sonoma) or later.

Option 1: Shell Installer (macOS / Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/fluree/db/releases/latest/download/fluree-db-cli-installer.sh | sh

Option 2: Homebrew (macOS / Linux)

brew install fluree/tap/fluree

fluree installs stable releases only. To try a pre-release, install fluree-beta, which follows the newest release, pre-release or stable. It installs beside fluree without replacing the fluree on your PATH, so you run it by its path:

brew install fluree/tap/fluree-beta
"$(brew --prefix fluree/tap/fluree-beta)/bin/fluree" --version

To make the beta your default fluree, put $(brew --prefix fluree/tap/fluree-beta)/bin first in your PATH; take it out to go back to the stable release. When a stable release supersedes the beta, brew upgrade moves fluree-beta to it.

Option 3: PowerShell (Windows)

Open PowerShell and run:

irm https://github.com/fluree/db/releases/latest/download/fluree-db-cli-installer.ps1 | iex

Then open a new PowerShell session and verify fluree --version. The installer adds %USERPROFILE%\bin to your PATH. The binary is unsigned, so Windows SmartScreen may prompt on first run — click More info → Run anyway.

Option 4: Download Pre-built Binary

Download the latest release for your platform from GitHub Releases:

# Linux (x86_64)
curl -L https://github.com/fluree/db/releases/latest/download/fluree-db-cli-x86_64-unknown-linux-gnu.tar.xz | tar xJ
chmod +x fluree-db-cli-x86_64-unknown-linux-gnu/fluree

# macOS 14 or later (Apple Silicon)
curl -L https://github.com/fluree/db/releases/latest/download/fluree-db-cli-aarch64-apple-darwin.tar.xz | tar xJ
chmod +x fluree-db-cli-aarch64-apple-darwin/fluree

Option 5: Build from Source

If you have Rust installed:

# Clone the repository
git clone https://github.com/fluree/db.git
cd db

# Build the CLI (includes embedded server)
cargo build --release -p fluree-db-cli

# Binary will be at target/release/fluree

Option 6: Docker

# Pull the image
docker pull fluree/server:latest

# Run the container
docker run -p 8090:8090 fluree/server:latest

For configuration (mounted JSON-LD/TOML config files, env vars, persistent volumes, S3+DynamoDB, query peers, full Compose example), see Running with Docker.

Start the Server

Default Storage (Development)

fluree server run needs a Fluree project directory; create one with fluree init if you haven’t. By default the server stores data in the project’s .fluree/storage directory:

fluree init
fluree server run

You should see output like:

INFO fluree_db_cli::commands::server: Starting Fluree server (foreground) version="…" addr=0.0.0.0:8090 storage="file"

Memory Storage (Throwaway)

To try the server without creating a project, keep the data in memory. Nothing is written to the current directory, and the data is gone when the server stops:

fluree server run --memory

File Storage (Persistent)

For persistent storage, specify a storage path:

fluree server run --storage-path /var/lib/fluree

Custom Port

fluree server run --listen-addr 0.0.0.0:9090

Debug Logging

fluree server run --log-level debug

Verify Installation

Check Server Health

curl http://localhost:8090/health

Expected response:

{
  "status": "ok",
  "version": "4.0.4"
}

Create a Ledger

curl -X POST http://localhost:8090/v1/fluree/create \
  -H "Content-Type: application/json" \
  -d '{"ledger": "test:main"}'

Insert Data

curl -X POST "http://localhost:8090/v1/fluree/insert" \
  -H "Content-Type: application/json" \
  -H "fluree-ledger: test:main" \
  -d '{
    "@context": {"ex": "http://example.org/"},
    "@id": "ex:alice",
    "ex:name": "Alice"
  }'

Query Data

curl -X POST "http://localhost:8090/v1/fluree/query" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "test:main",
    "select": {"?s": ["*"]},
    "where": [["?s", "ex:name", "?name"]]
  }'

Understanding the Server

Endpoints

Default server endpoints:

EndpointMethodDescription
/healthGETHealth check
/v1/fluree/createPOSTCreate a ledger
/v1/fluree/dropPOSTDrop a ledger
/v1/fluree/queryGET/POSTExecute queries
/v1/fluree/insertPOSTInsert data
/v1/fluree/updatePOSTUpdate with WHERE/DELETE/INSERT
/v1/fluree/eventsGETSSE event stream

See the API Reference for complete endpoint documentation.

Storage Modes

File (default; .fluree/storage, or set with --storage-path):

  • Persistent local file storage
  • Data survives restarts
  • Best for single-server deployments

Memory (--memory; see Storage Modes):

  • Fast, in-process storage
  • Data lost on restart
  • Best for development, testing, and CI

Configuration

All options can be set via CLI flags or environment variables. fluree server run takes the most common server flags directly; pass any other server flag after -- (for example fluree server run -- --cache-max-mb 4096):

# CLI flag
fluree server run --storage-path /data --log-level debug

# Environment variables
export FLUREE_LISTEN_ADDR=0.0.0.0:9090
export FLUREE_LOG_LEVEL=debug
fluree server run

See Configuration for all options.

Common Configurations

Development

fluree server run --log-level debug

Production (Single Server)

fluree server run \
  --storage-path /var/lib/fluree \
  -- \
  --indexing-enabled \
  --events-auth-mode required \
  --events-auth-trusted-issuer did:key:z6Mk...

With Background Indexing

fluree server run \
  --storage-path /var/lib/fluree \
  -- \
  --indexing-enabled

Docker Deployment

For the full Docker guide — image internals, configuration via env vars vs mounted JSON-LD/TOML config files, persistent volumes, LRU cache and indexing tuning, S3+DynamoDB connection configs, query peers, and a production-ready Compose example — see Running with Docker.

Minimal persistent run:

docker run -d --name fluree \
  -p 8090:8090 \
  -v fluree-data:/var/lib/fluree \
  fluree/server:latest

Troubleshooting

Port Already in Use

# Use a different port
fluree server run --listen-addr 0.0.0.0:9090

Permission Denied (File Storage)

sudo chown -R $USER:$USER /var/lib/fluree
chmod -R 755 /var/lib/fluree

Server Won’t Start

Check logs with debug level:

fluree server run --log-level debug

Connection Refused

Verify the server is running and check the listen address:

# Listen on all interfaces (not just localhost)
fluree server run --listen-addr 0.0.0.0:8090

Next Steps

Now that your server is running:

  1. Create a Ledger - Set up your first database
  2. Write Data - Insert your first records
  3. Query Data - Retrieve and explore your data

For production deployments: