Deployment Guide

This guide covers FLUX deployment and TypeScript-first verification.

Deployment Modes

1. Docker Compose (recommended)
2. Docker run
3. Native binary

Prerequisites

• Docker 24+ and Docker Compose v2 (container deployment)
• Go 1.24+ (native deployment)
• Node.js 18+ (TypeScript SDK checks)
• TCP 9092 reachable for clients

Runtime Configuration

Variable	Default	Description
FLUX_LISTEN_ADDR	:9092	broker listen address
FLUX_DATA_DIR	data (native) / /app/data (container)	storage root
FLUX_NUM_PARTITIONS	3	partition count
FLUX_REPLICATION_FACTOR	3	total replicas per partition (leader + followers, local simulation)
FLUX_MIN_ISR	2	minimum ISR required for committed writes
FLUX_REPLICA_MAX_LAG	0	max offset lag to remain in ISR
FLUX_REPLICA_LAG_TIMEOUT_MS	10000	follower freshness timeout for ISR
FLUX_ACK_ALL_TIMEOUT_MS	2000	timeout for acks=all produce waits
FLUX_SEGMENT_MAX_BYTES	1048576	segment rollover threshold
FLUX_RETENTION_MAX_BYTES	52428800	retention by max bytes
FLUX_RETENTION_MAX_AGE_SECONDS	86400	retention by max age
FLUX_FLUSH_INTERVAL_MS	1000	interval for interval fsync mode
FLUX_FLUSH_BYTES	65536	bytes threshold for interval fsync mode
FLUX_FSYNC_MODE	always	one of always, interval, never

Option 1: Docker Compose

From project root (flux/):

docker compose up --build -d

Verify:

docker compose ps
docker compose logs -f broker

Stop:

docker compose down

Stop and remove persisted data:

docker compose down -v

Option 2: Docker Run

Build image:

docker build -t flux-broker:latest .

Run container:

docker run -d \
  --name flux-broker \
  -p 9092:9092 \
  -e FLUX_LISTEN_ADDR=:9092 \
  -e FLUX_DATA_DIR=/app/data \
  -e FLUX_NUM_PARTITIONS=3 \
  -v flux_data:/app/data \
  --restart unless-stopped \
  flux-broker:latest

Option 3: Native Binary

Build:

go build -o bin/flux-broker ./cmd/broker

Run:

FLUX_LISTEN_ADDR=:9092 \
FLUX_DATA_DIR=./data \
FLUX_NUM_PARTITIONS=3 \
FLUX_REPLICATION_FACTOR=3 \
FLUX_MIN_ISR=2 \
./bin/flux-broker

Post-Deploy TypeScript Functional Check

Run SDK example:

cd packages/sdk/typescript
npm install
npm run build
npx tsc --module commonjs --target es2020 --outDir examples/dist examples/basic-usage.ts
node examples/dist/basic-usage.js

Expected behavior:

• producer sends messages successfully
• consumer runs with assignment callbacks
• message handling logs appear
• graceful disconnect completes

Data Layout (Current)

Typical files under FLUX_DATA_DIR:

orders-2-segment-000000.log
orders-2-offset.idx
orders-2-time.idx
orders-2-replica-1-segment-000000.log
orders-2-replica-2-segment-000000.log
offsets.json
groups.json

Current Deployment Limits

• single broker process
• no distributed metadata quorum
• no network replication failover behavior
• local replica files are same-node mirrors, not cluster replication