1 Storage Layout
Forgejo Actions edited this page 2026-09-25 17:00:22 +00:00

Storage Layout

The library root separates authoritative originals from regenerable data:

  • stored-objects/ — immutable originals, content-addressed by SHA-256 at stored-objects/sha256/<2>/<2>/<hash>.<ext>.
  • derived/ — regenerable thumbnails, previews, transcodes, and artifacts. Safe to lose; it can be rebuilt.
  • upload-staging/ — temporary, non-authoritative staging for in-progress uploads.
  • quarantine/ — files set aside rather than silently deleted.
  • exports/ — generated export artifacts.

PostgreSQL is the authoritative runtime metadata store; the filesystem alone is not enough to reconstruct the library.

Subdirectories can be mounted from separate host paths — for example derived/ on a local SSD while originals live on a NAS. HDD, CIFS, and NFS are supported only if they provide read-after-write consistency, atomic rename, stable locking, and durable writes. ML model caches are not backup state and do not need to be preserved.

See Backup and Restore for what must be captured for a faithful recovery.

Details