Skip to content

quickstart-server.md

Latest commit

 

History

History
288 lines (201 loc) · 6.36 KB

quickstart-server.md

File metadata and controls

288 lines (201 loc) · 6.36 KB
Raw

Quickstart: Run the Server

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

Installation

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

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 (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

Memory Storage (Development)

Start the server with in-memory storage (data is lost on restart):

fluree server run

You should see output like:

INFO fluree_db_server: Starting Fluree server
INFO fluree_db_server: Storage mode: memory
INFO fluree_db_server: Server listening on 0.0.0.0:8090

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:

Endpoint Method Description
/health GET Health check
/v1/fluree/create POST Create a ledger
/v1/fluree/drop POST Drop a ledger
/v1/fluree/query GET/POST Execute queries
/v1/fluree/insert POST Insert data
/v1/fluree/update POST Update with WHERE/DELETE/INSERT
/v1/fluree/events GET SSE event stream

See the API Reference for complete endpoint documentation.

Storage Modes

Memory (default):

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

File (with --storage-path):

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

Configuration

All options can be set via CLI flags or environment variables:

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

# Environment variables
export FLUREE_STORAGE_PATH=/data
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-issuers 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: