Storing blobs in S3

Set --s3-endpoint, --s3-bucket, --s3-access-key and --s3-secret-key and the encrypted blobs go to an S3-compatible bucket (AWS, MinIO, Cloudflare R2, Backblaze B2, Garage and so on) instead of the data directory. Requests are path-style. The SQLite database always stays local.

thencloud-server \
  --s3-endpoint https://s3.example.com \
  --s3-bucket thencloud \
  --s3-access-key ... --s3-secret-key ... \
  --s3-prefix thencloud/

Only ciphertext ever reaches the bucket, in the same <xx>/<version id>/<chunk> layout as on disk.

Mirror

With --s3-mirror true, every blob is kept in the data directory as well: written to both (an upload fails if either fails), read from the disk, and fetched from the bucket only when the disk doesn’t have it, which puts it back on the disk. The bucket becomes a live second copy.

Database snapshots

With S3 configured, the server puts a snapshot of the database in the bucket under db/ every --s3-snapshot-hours (24 by default), keeping the newest --s3-snapshots-kept (7). Restarts don’t skip one: the server checks the newest snapshot’s age when it starts.

So the bucket alone is enough to rebuild the server. If the disk is lost:

thencloud-server --data-dir /new/data <the same S3 options> restore-snapshot
thencloud-server --data-dir /new/data <the same S3 options>

Files uploaded after that snapshot aren’t in its database, and check lists their blobs as not referred to.

Snapshots hold what the server already has: wrapped keys and ciphertext, never a key or a name.

The bucket doesn’t hold <data dir>/link-token-key, the key public-link tokens are sealed under (the database keeps only their hashes). Keep a copy of that file somewhere else: without it a rebuilt server still opens every link, but owners can’t be shown the links they made before.