Published

SeaweedFS

Self-hosted S3-compatible object storage, written in Go and licensed Apache-2.0. One container serves the S3 API for backups, app uploads and media. Fits a single server that needs its own buckets instead of a cloud bucket.

Resources by load level

What the app itself needs at each level, next to what we recommend for a server that runs only this app.

Level	What it means	App requirements	Recommended
LightEstimate	Up to 50 GiB stored, about 250,000 objects in a few buckets, up to 5 transfers at once (backups of a few machines, one app's uploads).	0.5 vCPU · 0.5 GiB RAM · 64 GiB disk	0.72 vCPU · 2.1 GiB RAM · 82.915 GiB disk
MediumEstimate	Up to 500 GiB stored, about 2 million objects, up to 20 transfers at once (several apps and nightly backups of a small office).	1 vCPU · 1 GiB RAM · 626 GiB disk	1.32 vCPU · 2.7 GiB RAM · 729.215 GiB disk
HeavyEstimate	Up to 2,000 GiB stored, about 10 million objects, up to 50 transfers at once, still one node with no replication.	2 vCPU · 2 GiB RAM · 2,501 GiB disk	2.52 vCPU · 3.9 GiB RAM · 2,885.465 GiB disk

Recommended = app requirements + system baseline + safety headroom, under sizing policy 2026.10.0. Options stay at their defaults. “Estimate” means the sources give no number for that case, so it is worked out from them by the method stated under Components. How the numbers are built

Size it in the Stack Sizer

Ready-to-run files

Support level Supported

Compose template from the official sources; not yet verified by a run.

Create docker-compose

Components

What each component needs at each load level, before baseline and headroom.

vCPU / GiB RAM / GiB disk
Component	Light	Medium	Heavy	Sources
SeaweedFS (weed mini) (app)	0.5 / 0.5 / 64	1 / 1 / 626	2 / 2 / 2,501	[1][5][6][19][20][22][34][36]

How the estimates are worked out

SeaweedFS (weed mini) · Light: No upstream total for mini. RAM: index ~20 B per file × 250,000 = 5 MB, reads 5 × 4 MB chunks = 20 MB, plus ~0.2 GiB assumed for the Go runtime of master, volume, filer, S3, admin and worker in one process; ×2 for Go GC headroom → 0.5 GiB. vCPU: SigV4 checks and MD5 ETags of every upload → half a core. Disk: image 193,556,478 B compressed (0.18 GiB) + 529,553,408 B unpacked (0.493 GiB), both kept by the containerd store = 0.673 GiB; stored data ×1.25 for deleted space not yet vacuumed (a volume is compacted at 30% garbage) and filer metadata (an assumed margin). 0.673 + 50 × 1.25 = 63.2 → 64.
SeaweedFS (weed mini) · Medium: RAM: index 20 B × 2,000,000 = 40 MB, 20 reads and 20 uploads × 4 MB chunks = 160 MB, runtime 0.2 GiB → about 0.4 GiB live, ×2 for Go GC → 0.8, rounded to 1 GiB for the filer's LevelDB caches. vCPU: one core for signature checks, hashing and the background vacuum. Disk: image 193,556,478 B compressed (0.18 GiB) + 529,553,408 B unpacked (0.493 GiB), both kept by the containerd store = 0.673 GiB; stored data ×1.25 for deleted space not yet vacuumed (a volume is compacted at 30% garbage) and filer metadata (an assumed margin). 0.673 + 500 × 1.25 = 625.7 → 626.
SeaweedFS (weed mini) · Heavy: RAM: index 20 B × 10,000,000 = 200 MB (the wiki's leveldb index cuts this), 50 reads and 50 uploads × 4 MB = 400 MB, runtime 0.2 GiB → about 0.8 GiB live, ×2 for Go GC → 1.6, rounded to 2 GiB. vCPU: two cores for hashing at higher throughput plus vacuum and compaction of 1 GiB volumes. Disk: image 193,556,478 B compressed (0.18 GiB) + 529,553,408 B unpacked (0.493 GiB), both kept by the containerd store = 0.673 GiB; stored data ×1.25 for deleted space not yet vacuumed (a volume is compacted at 30% garbage) and filer metadata (an assumed margin). 0.673 + 2,000 × 1.25 = 2,500.7 → 2,501.

Ports

Public ports are meant to be reached from outside the stack, usually through a reverse proxy; internal ones stay on the stack's own network.

Component	Port	Exposure	Purpose	Sources
SeaweedFS (weed mini)	8333/tcp	Public, through a proxy	S3 API (SigV4, path-style) and the /healthz probe; serve only through an HTTPS reverse proxy	[1][6][8]
SeaweedFS (weed mini)	9333/tcp	Internal only	Master HTTP API and UI (volume assignment); no authentication	[6][25]
SeaweedFS (weed mini)	19333/tcp	Internal only	Master gRPC (HTTP port + 10000); mutual TLS only when configured	[6][25]
SeaweedFS (weed mini)	9340/tcp	Internal only	Volume server HTTP (object data); writes unprotected without a JWT signing key	[6][25]
SeaweedFS (weed mini)	19340/tcp	Internal only	Volume server gRPC (HTTP port + 10000)	[6][25]
SeaweedFS (weed mini)	8888/tcp	Internal only	Filer HTTP API and UI; reads and writes every file without auth unless JWT keys are set	[6][25]
SeaweedFS (weed mini)	18888/tcp	Internal only	Filer gRPC (HTTP port + 10000), used by the S3 gateway	[6][25]
SeaweedFS (weed mini)	18333/tcp	Internal only	S3 gateway gRPC (HTTP port + 10000)	[6]
SeaweedFS (weed mini)	23646/tcp	Internal only	Admin server; with -admin.ui=false only /health and /metrics	[6][11]
SeaweedFS (weed mini)	33646/tcp	Internal only	Admin worker gRPC (HTTP port + 10000) for the maintenance worker; no password auth	[6][28]

Every port in the catalog, with conflicts between apps

User and permissions (UID/GID)

The user each container's process runs as, and the paths it writes to. A bind mount for one of these paths must be writable by that UID:GID.

Component	UID:GID	User	Starts as root	Writes to	Sources
SeaweedFS (weed mini)	1000:1000	`seaweed`	Yes, prepares its directories, then drops to this user	`/data`	[4][5][12]

SeaweedFS (weed mini): The image has no USER: entrypoint.sh starts as root, chowns /data to seaweed (1000:1000) only when the owner differs, and drops privileges with su-exec. A bind mount of /data therefore needs no manual chown.

Storage growth

How much each component's data grows per month at each load level, on top of the disk in the profile. A value marked Assumption is ANAROQ's stated assumption, not a figure from the sources; the notes say what it rests on.

GiB per month
Component	Light	Medium	Heavy	Sources
SeaweedFS (weed mini)Assumption	2	20	80	[6][22]

What the growth figures rest on

SeaweedFS (weed mini): Growth is what clients upload minus what they delete; SeaweedFS expires nothing by itself (no lifecycle rule is set). Assumed net upload: 2, 20 and 80 GiB a month. Deleted objects free space only when vacuum compacts a volume with 30% garbage (checked every 840 s).

Upgrade and rollback

How to move to a new version safely, and how to go back if it fails.

Back up first

Stop the container (docker compose stop seaweedfs) and copy the whole /data volume: volume .dat/.idx files, the filer's LevelDB metadata, the master state and the .mini_* key files. Data and metadata must come from the same moment. [6][21][27]

Upgrade steps

Back up /data first (see backup). Then set the new pinned tag in the Compose file and run docker compose pull and docker compose up -d. Stay on the standard tag: _large_disk builds use another index format and cannot share the same data. [20][35]
Check docker compose logs seaweedfs and the /healthz check, then list a bucket with an S3 client. mini's defaults (volume size, ports, bundled services) can change between releases, so compare the flags in the new mini.go. [1][6][8]

Roll back

Stop the stack, restore the /data copy taken before the upgrade, pin the previous tag and run docker compose up -d. [20][27]DerivedThe FAQ promises backward-compatible upgrades but documents no downgrade, so running an older binary on data a newer one wrote is not assumed safe; restoring the copy is.

Known breaking changes

In 4.41: mini and master report anonymous cluster statistics to telemetry.seaweedfs.com by default (before: off). Opt out with -master.telemetry=false, as the template does. [6][33]DerivedRelease notes were not reachable from the research environment; taken from the flag default in mini.go at 4.40 (false) and 4.41 (true).
In 4.23: The image's default command became mini -dir=/data (before: no command, the container needed one such as server). Compose files that pass their own command are unaffected. [32]DerivedTaken from docker/Dockerfile.go_build at 4.22 and 4.23; the release notes were not reachable.
In 4.00: The image stopped running as root: 4.00 set USER seaweed (uid 1000), so data written by 3.x as root could not be opened. Since 4.01 the entrypoint starts as root and chowns /data first; upgrade 3.x straight to 4.01 or later. [30][31]DerivedTaken from docker/Dockerfile.go_build at 3.99 and 4.00 and docker/entrypoint.sh at 4.01; the release notes were not reachable.

Limits

One node, no replication: weed mini runs a single master and keeps one copy of each object, so a failed disk loses data. Protect /data with RAID or backups; multi-master and replication need the multi-component setup. [1][6]
Clients must use path-style addressing (https://host/bucket/key): the template sets no -s3.domainName, so bucket.host URLs are not routed. Most SDKs and rclone have a force-path-style setting. [8][13]
The S3 API covers buckets, objects, multipart, versioning, object lock and lifecycle, but not bucket notifications, bucket replication, SelectObjectContent or Object Lambda; check the wiki's API list before relying on a feature. [23][24]
The template has one admin identity from environment variables, with full access to every bucket. Scoped users need weed shell (s3.configure) or an -s3.config file, and the env keys change only with a restart. [1][15]
Behind a reverse proxy, uploads must stream: request buffering breaks chunked SigV4 signatures, and a body size limit caps object size. Caddy streams by default. [13]

Security

Without AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY the S3 gateway runs in Allow-All mode and accepts unsigned requests. The template makes both required; never remove them from .env. [1][7][15]
Only port 8333 is S3-authenticated. The master (9333), volume (9340) and filer (8888) HTTP ports and the gRPC ports have no login and are not published, but containers on the same Docker network can reach them; in the caddy or proxy-network mode that includes the proxy's network. [6][25]
To close the filer and volume HTTP ports, the wiki documents JWT keys as env vars (WEED_JWT_SIGNING_KEY, WEED_JWT_FILER_SIGNING_KEY and their _READ_ variants), which the S3 gateway then uses. Not in the template; test it before relying on it. [25][26]
The Admin UI is off: without a password its UI and /api routes are open to anyone who reaches port 23646. To turn it on, set WEED_ADMIN_PASSWORD, drop -admin.ui=false and reach it through an SSH tunnel only. [11][28][29]
Images are signed with cosign since September 2026; verify chrislusf/seaweedfs:4.48 against the release workflow identity in docker/README.md and deploy by the digest you checked. [18]

Backup

Simplest consistent backup: stop the container and copy the whole /data volume, or sync every bucket to another S3 target with an S3 client while it runs. Keep the .mini_sse_kek and .mini_kek_passphrase files: SSE-S3 objects cannot be read without them. [6][27]
Volume files and filer metadata must match: the wiki pairs weed backup of each volume with fs.meta.save of the metadata, taken while writes are paused. A copy of the volumes alone cannot restore object names. [27]