Storage
Attachment volume and file mix, the configured storage target, and settings-backed upload limits.
Overview
The Storage panel answers "how much are we holding, and what is it?" for the attachment estate — total file count and bytes, broken down by the entity the files hang off, by file type, by disk, and by category — alongside the storage target and the upload limits the system is actually enforcing.
Upload limits (maximum file size, files per entity, thumbnail dimensions, and
allowed media types) are settings-backed (uploads.*). Self-hosted installs
can edit them on this page with settings.manage. The hosted catalogue item may lock
the same keys in its own layer; core stays tenant-unaware. Viewing the panel
still requires only settings.view. Config and env values in
config/attachments.php remain the seed defaults until an operator saves.
Where it lives
Route: /admin/settings/storage (admin.settings.storage)
Open Admin → System → Storage. Requires settings.view.
Sections
- Headline counters — attachments, total size, thumbnails, largest file, and average file size
- Storage target — default disk, driver, bucket / region / root prefix / URL prefix where the driver exposes them, and whether unsigned download URLs are permitted
- By entity type — bytes per attachable entity (account, rental, catalogue item, …) as a share of the whole
- By file type — rolled up into families (Images, PDFs, Documents, Spreadsheets, Text & data, Archives, Video, Audio, Other), with the individual media types behind a disclosure
- By disk and category — per-disk totals, flagging any disk that is not the configured default, and per-category totals
- Upload limits — maximum file size, maximum files per entity, thumbnail dimensions, and allowed media types (editable with
settings.manage); how many entities have reached the per-entity cap; the per-entity cap chips
Notes
Attachment access follows the parent record and its warehouse. Reads require
the parent policy’s view permission; upload, rename and deletion require update.
Invoice and credit-note additions have a dedicated attachment ability using the
existing invoices.edit permission and parent visibility. Files may be added
after issue or invoice locking, but cannot be deleted from issued records or
locked invoices. Financial fields remain unchanged.
Uploading a file does not grant a permanent right to delete it. There is no
warehouse_id on attachments; administrative volume totals remain tenant-wide.
Workflow communication artifacts are separate from the attachment estate. Their immutable private bytes use the tenant-resolved object-storage disk on Signals Cloud and the private local disk on self-hosted installations whose resolved disk is public. They are therefore not included in this panel's attachment totals.
Figures are cached for five minutes. Every number is a grouped aggregate query — no attachment row is ever loaded — so the page costs a fixed handful of queries no matter how large the table grows. The cache is TTL-only: uploads and deletions do not bust it, because these are reporting aggregates rather than state the UI reads back after a write, and wiring the whole file pipeline into a cache bust to save an operator five minutes of staleness is a poor trade. The panel prints the calculation timestamp, and Recalculate drops the cached payload if you need the numbers now.
The S3 warning. If the default disk uses any driver other than s3, the
Storage target section says so. That is expected in local development and worth
investigating in production — Signals warehouses attachments on S3 by convention,
with signed, expiring download URLs.
Private attachment and export storage
New attachments, thumbnails and exports use ATTACHMENTS_DISK. When unset, the
configured filesystem disk is used unless it is local or public; those select
private local storage (storage/app/private). Custom disks must have private
visibility and must not be rooted inside the public web directory. Configure
private object access on the bucket too: a public bucket policy overrides an
object's private visibility. Keep this disk mounted in web and queue workers.
Stored names are generated by the server. Upload extensions come from the validated, detected MIME type, never the client filename or Content-Type header. The original filename is retained only as metadata and the download filename. The built-in MIME-to-extension map covers the shipped allow-list; adding a custom MIME type also requires a safe extension mapping. Uploads of unsupported custom types are refused with the detected MIME type and directions to remove the unsupported entry in Admin → System → Storage. Icons remain in their separate existing storage, with detected extensions and JPEG thumbnails.
Attachment DTOs and file pages issue signed links valid for at most five minutes.
The link requires a signed-in session or Sanctum token and checks the current
parent policy and warehouse again, then streams with attachment disposition and
X-Content-Type-Options: nosniff. A link does not grant access to a different
viewer. ATTACHMENTS_ALLOW_UNSIGNED_URLS applies only to public branding
helpers; it never enables unsigned attachment or export downloads.
Exports are streamed through their existing expiring token route, which rechecks the export creator's current authority. Generated document portal files retain their token, expiry and PIN checks; a portal token does not grant attachment access.
Related
- System Health — live disk connectivity probe
- Caching — cache backend health and TTLs
- Developer deep-dive: Caching Strategy