SeaweedFS

Last reviewed Aug 26, 2026 · 840 words

SeaweedFS is the S3-compatible store I now recommend for a homelab, and not for the reason its README leads with. Billions of files across racks is real and is why the catalogue marks it Hard, but the same binary runs as one process on one box with weed server -s3, uses about 100 MB of RAM idle, and serves restic, rclone and Immich over S3 without any of the cluster machinery. Start there. Scale out only when you have a second machine's worth of disks to pool.

Four roles, one binary

A master (port 9333) hands out file IDs and knows which volume server holds what. Volume servers (8080) store data in large append-only files, 30 GB each by default, which is the trick from Facebook's Haystack paper: a million tiny photos become a handful of big files and one disk seek per read. A filer (8888) adds paths and directories on top, keeping its metadata in an embedded LevelDB by default or in Postgres, MySQL or Redis if you ask. The S3 gateway (8333) sits on the filer and speaks enough of the S3 API for every client I have tried. weed server starts all four in one process, which is the mode that matters for most readers.

Single node with compose

services:
  seaweedfs:
    image: chrislusf/seaweedfs
    command: "server -dir=/data -s3 -s3.config=/etc/seaweedfs/s3.json -ip=seaweedfs -volume.max=0"
    ports:
      - "127.0.0.1:9333:9333"
      - "127.0.0.1:8888:8888"
      - "8333:8333"
    volumes:
      - /srv/seaweed:/data
      - ./s3.json:/etc/seaweedfs/s3.json:ro
    restart: unless-stopped

-volume.max=0 sizes volumes to the disk automatically. s3.json holds identities and what each may do:

{
  "identities": [
    {
      "name": "backup",
      "credentials": [{"accessKey": "AKIABACKUP0001", "secretKey": "a-long-random-secret"}],
      "actions": ["Read", "Write", "List", "Tagging"]
    }
  ]
}

Without that file the S3 port accepts anyone, so write it before you publish 8333 anywhere. Buckets are directories under /buckets in the filer; rclone mkdir seaweed:photos or aws s3 mb creates one. Put a TLS-terminating proxy in front of 8333 and you have the replacement for the Amazon S3 bucket you were paying for, on hardware you own.

restic, rclone and Immich are the three jobs it does well

Point restic at s3:http://seaweed.lan:8333/backups with the access keys above and it behaves exactly as it does against AWS; snapshots, prune and check all work, and pruning a repository is fast because SeaweedFS handles the thousands of small pack deletions without the latency S3 charges you in both time and money. rclone treats it as any other S3 remote, which makes it the middle hop for a "copy to a friend's house" tier in a 3-2-1 scheme. Immich does not need S3 itself, but weed mount exposes the filer as a FUSE filesystem, and I keep the Immich upload directory on it so photos land in replicated storage the moment they arrive.

Replication and erasure coding are where "Hard" lives

Each collection or volume carries a replication string: 000 means one copy, 001 means a second copy on another server in the same rack, 010 another rack, 100 another data centre. Two boxes with 001 means one can die and everything is still served. Erasure coding (10 data plus 4 parity shards, via ec.encode in weed shell) cuts that overhead from 2x to 1.4x for cold data at the price of slower writes and more moving parts. Cloud tiering (volume.tier.move) pushes whole volumes to a real S3 bucket while keeping metadata local. All of that is powerful and all of it is operations work: you own balancing, you own the filer store, and you own the rebuild after a disk dies. The "ops expertise required" con means exactly this.

SeaweedFS against MinIO and Garage

MinIO was the default answer for years, and its community edition has been shedding features and attention since 2025, which is a large part of why people are looking again. Garage is the lighter, more conservative choice if all you want is replicated S3 across a few slow links. SeaweedFS wins on small files, on the FUSE mount, and on the ceiling.

What I'd do

One weed server -s3 container on the box with the most disk, s3.json written before the port is opened, restic and rclone pointed at it, and a nightly weed shell volume.list in the monitoring to catch a full disk. Add a second node with 001 replication when a second box appears. Do not turn on erasure coding or cloud tiering until you have restored from the setup you already have.