Documentation

Everything you need to evaluate, run and build on WarrenFS: what a write guarantees, how the cluster behaves when nodes fail, how to deploy and operate it, and every setting, route, command and metric.

WarrenFS in one minute

Two copies before the ack. A write streams to both replicas of a volume at once, on different nodes. The key comes back only when both have fsynced the file and agree on its size and SHA-256. See What an acknowledgement means.
Plain files. Data is files in a directory on ext4 or XFS, grouped into volumes of up to 100 GB. A key names the volume, never the node, so moving data never breaks a key. See Volumes and keys.
Failure is routine. A volume with a silent replica stops taking writes and new writes go elsewhere; after 15 minutes the silent node is replaced from the surviving copy, checked file by file. See A node goes quiet.
Two ways in. An HTTP API by key for apps that keep their own records, or paths in a bucket, mounted with FUSE or the CSI driver, for apps that use plain files. See Names and the mount.
One binary, no outside coordinator. The volume map lives in Raft inside WarrenFS, so the same binary runs in Kubernetes, on bare metal or standalone on a laptop. See Three modes.

Where to start

Evaluating it

Read these in order; together they take about half an hour.

Why WarrenFS: the problem, the options that were ruled out, and the trade-offs made on purpose.
Architecture: one binary per node, volumes and keys, the volume map, health.
Writes, reads and deletes: the write path step by step, and the consistency model.
Failures and repair: a node failure minute by minute, and the cases two copies cannot cover.

Trying it

Quickstart: build the binary, start one instance, store a file by key and by path, read it back with a range, and mount the bucket. Five minutes, no cluster needed.

Running it

Kubernetes: cluster mode as a DaemonSet, and buckets mounted into pods with the CSI driver.
Bare metal: the same binary under systemd, with mutual TLS between machines.
Day two: status, draining and adding nodes, rebalancing, upgrades, and the alerts worth having.

Building on it

HTTP API: every route, header and status code.
Names and the mount: buckets, paths, and what the mount accepts and refuses.
Client apps: how an app finds the instance on its node and authenticates.

Guarantees and limits at a glance

Question	Answer	More
Is a file safe when the write returns?	Yes: it is on two nodes, fsynced on both, with matching size and SHA-256.	Writes
Does one node down stop writes?	No. Its volumes turn read-only and writes go to volumes whose replicas are all healthy.	Failures
Does one node down stop reads?	No. Every file has a second copy on another node.	Failures
Can two nodes down lose data?	Only a volume whose two replicas were on exactly those nodes: unreachable until one is back, lost only if both disks are lost.	Two nodes down
What about silent corruption?	Every file is re-read against its checksum every week, and a bad copy is replaced from the other.	Scrub
Can a file change under a key?	Never. An edit is a new file with a new key; a name can be pointed at the new file.	Consistency
Is it a backup?	No. Replication protects against failing hardware, not against deleting the wrong file.	Not protected
Does it speak S3?	No. It has its own small HTTP API, and POSIX through the mount.	HTTP API
Can it hold databases or logs?	No. Anything changed in place or appended to belongs on a local disk or a block volume.	What not to put on it

Reference

Configuration: every setting, its default and its environment variable, and the secrets.
CLI: every warrenfs command and its flags.
Metrics: every Prometheus metric, and the queries worth keeping.

Next: the case for WarrenFS, in Why WarrenFS.