Local S3 objects

CROWDB is a distributed storage platform with an S3-compatible object data plane and a multi-group Multi-Paxos key-value foundation. This guide starts with the shortest usable path: create a persistent local S3 cluster and use bucket and object operations. The later sections cover the underlying KV cluster, physical topology, individual servers, upgrades, and recovery.

CROWDB provides three user-facing interfaces:

• Web UI — the crowdb-web service provides a visual dashboard with cluster topology, group health, a KV Operator panel (store/group selector, paginated scan, inline CRUD, demo data injection), and Swagger UI for browsing the OpenAPI spec of any registered crowdb-kv-server instance.
• CLI — crowdb-cli s3 owns the local S3 cluster lifecycle and sends bucket/object requests directly to the cluster recorded by --root. Lower-level management commands discover services through group 0 and call them directly. Output is a human-readable console transcript.
• HTTP APIs — the local access server exposes the S3 HTTP API. The console service exposes the lower-level cluster management API documented in §8.

S3 examples use the loopback access endpoint. The first local cluster normally receives 127.0.0.1:16000; when that port is already assigned, use the endpoint printed by s3 cluster start or `s3 cluster status.

S3_ENDPOINT=http://127.0.0.1:16000

Prerequisites

Before following the steps below:

• Run pixi run build from the repository root.
• Add target/release to PATH, or invoke the binaries by their full paths.
• Choose a dedicated cluster directory. The directory is the persistent cluster identity and contains configuration, logs, and data files.

1. Quick Start: Persistent Local S3

1.1 Start or restart the cluster

Choose a directory and start the cluster:

S3_ROOT="$PWD/.crowdb-runtime/persistent/s3-local"
crowdb-cli s3 cluster start --root "$S3_ROOT"

An absent or empty directory creates a new file-backed cluster. A recognized cluster directory restarts the same cluster with its existing data and port assignments. A non-empty directory that is not a CROWDB cluster is rejected without modification.

The command prints the S3 endpoint, Web management URL, running service count, and cluster root. The default local endpoints are:

S3_ENDPOINT=http://127.0.0.1:16000
WEB_URL=http://127.0.0.1:14000

If the command prints different endpoints because a default port is already assigned, use the printed values. Open WEB_URL for the topology, service, and cluster management console.

Inspect the recorded processes without changing them:

crowdb-cli s3 cluster status --root "$S3_ROOT"

The CLI owns S3 mini-cluster lifecycle. The bundled Web service loads that mini-cluster's console registry and presents its running services.

1.2 Bucket operations

Create a bucket:

crowdb-cli s3 bucket put --root "$S3_ROOT" photos
curl -X PUT "$S3_ENDPOINT/photos"

List buckets:

crowdb-cli s3 bucket list --root "$S3_ROOT"
curl "$S3_ENDPOINT/"

GET one bucket and show its XML result:

crowdb-cli s3 bucket get --root "$S3_ROOT" photos
curl "$S3_ENDPOINT/photos"

Remove an empty bucket:

crowdb-cli s3 bucket delete --root "$S3_ROOT" photos
curl -X DELETE "$S3_ENDPOINT/photos"

Removing a non-empty bucket returns the S3 error and leaves its objects intact.

1.3 Object CRUD

Create the bucket used by the following examples, then upload an object from a file, literal text, generated random bytes, or standard input:

crowdb-cli s3 bucket put --root "$S3_ROOT" documents

crowdb-cli s3 object put --root "$S3_ROOT" \
  documents reports/hello.txt --file ./hello.txt

crowdb-cli s3 object put --root "$S3_ROOT" \
  documents reports/text.txt --text 'object content'

crowdb-cli s3 object put --root "$S3_ROOT" \
  documents reports/random.bin --random-size 1048576

printf 'hello from CROWDB\n' | crowdb-cli s3 object put \
  --root "$S3_ROOT" documents reports/stdin.txt

curl -X PUT --data-binary @hello.txt \
  "$S3_ENDPOINT/documents/reports/hello.txt"

put creates a new object or replaces the bytes of an existing key.

Read an object to standard output or a file:

crowdb-cli s3 object get --root "$S3_ROOT" \
  documents reports/hello.txt

crowdb-cli s3 object get --root "$S3_ROOT" \
  documents reports/hello.txt --output ./downloaded.txt

curl "$S3_ENDPOINT/documents/reports/hello.txt" \
  --output ./downloaded-with-curl.txt

Check that an object exists:

crowdb-cli s3 object head --root "$S3_ROOT" \
  documents reports/hello.txt

curl -I "$S3_ENDPOINT/documents/reports/hello.txt"

Delete an object:

crowdb-cli s3 object delete --root "$S3_ROOT" \
  documents reports/hello.txt

curl -X DELETE "$S3_ENDPOINT/documents/reports/hello.txt"

1.4 List objects

List the first 100 keys below a prefix:

crowdb-cli s3 object list --root "$S3_ROOT" documents \
  --prefix reports/ --limit 100

curl --get "$S3_ENDPOINT/documents" \
  --data-urlencode 'list-type=2' \
  --data-urlencode 'prefix=reports/' \
  --data-urlencode 'max-keys=100'

When a response is truncated, pass its opaque continuation token unchanged:

crowdb-cli s3 object list --root "$S3_ROOT" documents \
  --prefix reports/ --limit 100 --continuation "$TOKEN"

curl --get "$S3_ENDPOINT/documents" \
  --data-urlencode 'list-type=2' \
  --data-urlencode 'prefix=reports/' \
  --data-urlencode 'max-keys=100' \
  --data-urlencode "continuation-token=$TOKEN"

1.5 Read a byte range

Ranges are inclusive. --range 3-9 returns seven bytes:

crowdb-cli s3 object get --root "$S3_ROOT" \
  documents reports/hello.txt --range 3-9

curl -H 'Range: bytes=3-9' \
  "$S3_ENDPOINT/documents/reports/hello.txt"

1.6 Stop, restart, and delete

Stop every process while preserving the cluster directory and stored objects:

crowdb-cli s3 cluster stop --root "$S3_ROOT"

Restart from the same directory and read the same data:

crowdb-cli s3 cluster start --root "$S3_ROOT"
crowdb-cli s3 object get --root "$S3_ROOT" \
  documents reports/hello.txt

Permanently stop the cluster, release its port assignments, and remove its directory:

crowdb-cli s3 cluster delete --root "$S3_ROOT"

delete is destructive. Use stop when the cluster must be started again. Cluster lifecycle does not currently have an HTTP management endpoint.