Description
Self-Hosted Disk File Storage supplies the upload and download backend for a local Dots instance. Objects are written beneath the instance’s local home in a company-specific directory, preserving tenant separation even though all bytes live on one machine. The uploader creates object keys, writes content, and returns the metadata expected by the same file routes used in hosted deployments.
Download and signing operations resolve stored paths through canonical containment checks rather than joining caller-controlled strings blindly. Company and object coordinates are validated before filesystem access, and traversal attempts are rejected. The backend is composed automatically by the local runtime so users can attach and retrieve files without provisioning an external object-storage service.
Selling Points
- Keeps uploaded documents on the same machine as the local database for a complete local-first data plane.
- Requires no S3 account or cloud bucket to make file-backed Dots workflows usable.
- Separates files by company and validates containment, protecting one local tenant from another’s directory.
- Uses the standard uploader contract, so API consumers see consistent file behavior across hosted and local deployments.
- Includes files in local backup, restore, and migration workflows instead of leaving attachments behind.
User Story
A researcher running bundled Dots attaches PDFs and images to rows while offline. The API writes those objects beneath the local instance’s company directory and returns normal file metadata. Later, the researcher opens the attachment through Dots and the runtime resolves the safe local path. A backup captures both the database references and file directory.
Extension Surface
This feature is configurable. packages/local-runtime/src/paths.ts places the files root under the configured local home, and packages/local-runtime/src/runtime/compose.ts selects the disk uploader for local composition. Operators can relocate the entire local home through supported configuration, but they cannot register arbitrary storage drivers through this surface; hosted object storage is composed elsewhere.
Capabilities & Limits
- Uploads, signs, and serves files through the standard runtime storage contract.
- Isolates object paths beneath per-company directories and rejects traversal.
- Participates in local data reset, support sizing, backup, restore, and migration.
- Limit: availability and capacity are bounded by the host machine’s filesystem.
- Limit: this backend is not a multi-node replicated object store and should not be treated as one.
Implementation Map
packages/local-runtime/src/storage/disk-uploader.tspackages/local-runtime/src/runtime/compose.tspackages/local-runtime/src/paths.tspackages/local-runtime/src/runtime/compose.storage.test.ts