Quickstart¶
The fastest path to a running IOLake is the all-in-one binary
(iolake-aio). It runs meta + OSD + gateway as tokio tasks in a
single process, shares one log stream, and is shut down with a single
Ctrl-C. Same wire protocol as a real cluster — what's different is
that there is no HA and, by default, no redundancy and no
authentication.
This page covers three paths:
| Path | Platform | Best for |
|---|---|---|
| AIO release binary | Linux (amd64, arm64), macOS (Apple Silicon) | Laptop-local S3/Iceberg/Delta endpoint |
| AIO built from source | Linux, macOS (Intel too) | Tracking main, or a platform with no release binary |
| AIO with several OSDs | as above | Erasure coding (e.g. 4+2) inside one process |
For a cluster of separate processes, use the Helm chart (on kind
locally: make kind-up, see Kubernetes) or
Linux.
IOLake is POSIX-only — no native Windows build. The storage
engine uses O_DIRECT, ioctl BLKGETSIZE64, and other unix-only
interfaces; there is no meaningful cfg-gate to Windows.
1. AIO release binary (fastest)¶
Each release publishes iolake-aio for three platforms, named with the
release tag: iolake-aio-<tag>-linux-amd64, -linux-arm64 and
-darwin-arm64, each with a .sha256, plus SHA256SUMS.txt. There is
no Intel macOS binary (build it), and no
archive of the other binaries. The current release, v0.1.0-rc.4, is a
pre-release, which GitHub's releases/latest link skips: name the tag.
TAG=v0.1.0-rc.4
PLATFORM=linux-amd64 # or linux-arm64, darwin-arm64
BASE=https://github.com/io-lake/iolake/releases/download/$TAG
curl -LO $BASE/iolake-aio-$TAG-$PLATFORM
curl -LO $BASE/iolake-aio-$TAG-$PLATFORM.sha256
shasum -a 256 -c iolake-aio-$TAG-$PLATFORM.sha256
chmod +x iolake-aio-$TAG-$PLATFORM
sudo mv iolake-aio-$TAG-$PLATFORM /usr/local/bin/iolake-aio
iolake-aio
On macOS, see Gatekeeper before the first run.
What you get¶
On start, AIO prints where it listens, the admin access key and secret,
and a ready-to-paste aws command:
━━━ IOLake ready ━━━
S3 / Iceberg / Delta Sharing : http://localhost:9000
Console : http://localhost:9000/_console/
LAN bind : 0.0.0.0 — reachable from other hosts on the network
Data directory : /tmp/.tmpXXXXXX
Internals (loopback only) : meta=:… osd=[…] (monolith — same process)
Admin access key : AKIA…
Admin secret key : …
SSE master key : persisted at /tmp/.tmpXXXXXX/master_key (set IOLAKE_MASTER_KEY to override)
AWS_ACCESS_KEY_ID=AKIA… AWS_SECRET_ACCESS_KEY=… \
aws --endpoint-url http://localhost:9000 s3 mb s3://test
The credentials are also in <data>/meta/admin-creds.env, readable by
its owner only. Authentication is off unless you pass --auth:
without it the gateway serves every request, signed or not, so keep aio
on a trusted network or bind it to loopback (--listen-addr 127.0.0.1).
Smoke test from another terminal:
export AWS_ACCESS_KEY_ID=... # from the banner above
export AWS_SECRET_ACCESS_KEY=...
aws --endpoint-url http://localhost:9000 s3 mb s3://demo
echo 'hello iolake' | aws --endpoint-url http://localhost:9000 s3 cp - s3://demo/hello.txt
aws --endpoint-url http://localhost:9000 s3 cp s3://demo/hello.txt -
Flags you'll actually use¶
| Flag | Default | Notes |
|---|---|---|
--port |
9000 |
Public port. Only port the caller needs to know. |
--listen-addr |
0.0.0.0 |
Use 127.0.0.1 to restrict to loopback. |
--data <dir> |
tempdir | Persist data across restarts. Holds meta/ (with admin-creds.env), osd-N/ and master_key. |
--auth |
off | Turn SigV4 authentication on. |
--osds <N> |
1 |
OSDs to run. Without --ec-k/--ec-m the pool is replication 1: no redundancy, however many OSDs. |
--ec-k, --ec-m |
0 |
Erasure code instead, with at least k+m OSDs: --osds 6 --ec-k 4 --ec-m 2. |
--strict-port |
off | Fail fast on --port conflict instead of picking an ephemeral. |
iolake-aio --help has the complete surface; the
configuration reference lists more.
2. AIO built from source¶
git clone https://github.com/io-lake/iolake
cd iolake
cargo build --release --bin iolake-aio
./target/release/iolake-aio
The toolchain and build dependencies are in
Linux and
macOS. Build the console
first (cd console && npm ci && npm run build) if you want /_console/;
without it aio serves an empty console.
3. AIO with erasure coding¶
iolake-aio --data "$HOME/.iolake" --osds 6 --ec-k 4 --ec-m 2
Six OSDs, each on a file-backed disk in the data directory
(--disk-size sets its size; 10 GiB, sparse, by default), with a 4+2
pool spread over them. It is still one process on one machine: it
survives the loss of two OSDs' disks, not of the machine.
Where to go next¶
- linux.md — binaries, building from source, systemd
- macos.md — macOS dev-loop specifics (why AIO-only, no prod OSD)
- docker.md — the container image and the Dockerfile's targets
- kubernetes.md — Helm chart, Kind demo, StatefulSet layout
- topologies.md — when to pick single-node / rack-aware / multi-DC
- configuration.md — flag / env / TOML reference