Candybox

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

A node reads conf/candybox.properties. Every key can be overridden by an environment variable named CANDYBOX_<KEY> (dots become underscores, upper-cased) — for example CANDYBOX_ZOOKEEPER_CONNECT — and the environment value wins. This makes it easy to ship one image and configure each instance through the environment.

Common keys#

Key	Meaning	Default
`node.id`	Cluster-unique node id. Falls back to the trailing number in `$HOSTNAME` (so a Kubernetes pod `candybox-2` becomes node `2`).	—
`zookeeper.connect`	ZooKeeper connect string, shared by BookKeeper and Candybox coordination.	`127.0.0.1:2181`
`server.bind`	Address clients connect to.	`0.0.0.0:9709`
`server.advertised`	Address published to the cluster for routing (set to a reachable hostname).	bind address
`health.port`	HTTP port for `/healthz`, `/readyz`, `/metrics`.	`9710`
`quorum.*`	BookKeeper replication per ledger role (`E/Qw/Qa`).	`3/3/2` (WAL, manifest), `3/2/2` (data)
`multipart.upload.ttl.millis`	How long an abandoned multipart upload is kept before a background sweep aborts it.	7 days
`rename.intent.abandon.millis`	Cross-partition rename: how long the source owner keeps a rename intent whose destination rendezvous marker never appears before dropping it (the source stays live).	60000 (60 s)

Full reference#

The complete, commented list of keys lives in candybox.properties.example, and the CandyboxConfig section of OPERATIONS.md documents the operational meaning of each tunable, including the security, consistency, and garbage collection settings.

Quick start

Mon, 01 Jan 0001 00:00:00 +0000

Quick start#

The fastest way to try Candybox is the bundled Docker Compose stack. It starts the full system — ZooKeeper, 3 BookKeeper bookies, 3 Candybox nodes, and the S3 gateway (on :9711) — using the published zetaplusae/candybox image.

With Docker Compose (recommended)#

From a checkout of the repository:

docker compose up -d
docker compose run --rm cli create-box photos
echo 'hello candybox' | docker compose run --rm -T cli put photos hello.txt
docker compose run --rm cli get photos hello.txt # -> hello candybox

Tear it down with docker compose down (add -v to also wipe the data volumes).

Concepts

Mon, 01 Jan 0001 00:00:00 +0000

Concepts#

Candybox borrows the bucket/object model from S3 but gives the pieces its own names.

Vocabulary#

Term	Meaning
Box	a bucket — a named, flat namespace of keys
Candy	an object — the bytes plus metadata stored under a key
CandyKey	an object key
Syrup	a data ledger that holds object bytes
CandyLocator	the small pointer the index stores to find a Candy’s bytes inside a Syrup

(Candy in a box — that’s the whole theme.)