[Idea] Local file uploads

[inzsome]

Affected area

Self-hosting and operations

Problem or opportunity

Currently file uploads are only possible with a S3 instance.

Desired outcome

File uploads should be possible without a S3 instance and should be stored within a docker volume when self-hosting. Additionally, it would be nice to have a way to backup/migrate files from a S3 instance to a local docker volume.

Alternatives or workarounds

I currently use a local S3 instance, however, this seems cumbersome and bloated.

Additional context

No response

Before submitting

• I searched existing issues for similar ideas.
• I removed personal, financial, and secret information from this public proposal.

[pullfrog]

Plan: Local file uploads without S3 (issue #86)

Current architecture (what a change must touch)

All upload handling is S3-only, and it splits into four surfaces:

• Mint — apps/api/src/routes/upload.ts returns presigned S3 PUT URLs (mintUploadPresign, mintProfileImagePresign, mintImportDocumentPresign, mintCloudImportDocumentPresign), wrapped as tRPC mutations in trpc/routers/uploads/index.ts. The web client just does fetch(uploadUrl, { method: 'PUT', body: file }) (apps/web/src/lib/upload.tsx:146) — it never talks to S3 directly beyond that URL.
• Server reads — lib/storage.ts getS3Object (used by the export bundle readers), plus HeadObject/GetObject in upload validation/promotion (validateProfileImageUpload, verifyAndPromoteImportDocument, verifyAndPromoteCloudImportDocument).
• Browser reads — the persisted fileUrl is rendered straight into <img src> / download links and handed to the AI provider for receipt extraction (data: imageUrl). Today these are public S3 URLs.
• Config/deploy — S3_UPLOAD_* in lib/env.ts, all four compose files, .env.example, container.env.example, README.md, docs/deployment.md. The worker never touches storage, so only the API image needs the volume.

Two properties make this tractable:

1. The client's upload flow is uniform — it PUTs bytes to whatever uploadUrl the API returns. A local backend can return an API upload route instead of a presigned URL with zero web-client changes.
2. The persisted fileUrl is a plain URL string in the DB (expense documents + Account.image), so backend switching and migration are about keys and URL rewriting, not data-model changes.

Design

Introduce a storage-driver abstraction (s3 and local) behind one interface in apps/api/src/lib/storage/: uploadsConfigured(), getUploadUrl(...), getObject(key), headObject(key), copyObject(srcKey, dstKey), deleteObject(key), publicUrlForKey(key), keyFromFileUrl(url). The S3 driver wraps the existing presign + SDK code; the local driver is a filesystem implementation rooted at UPLOADS_DIR.

In local mode:

• uploadUrl = {API_ORIGIN}/uploads/<key> (session- or token-authorized PUT).
• fileUrl = {API_ORIGIN}/uploads/<key> (browser GET).
• Promotion (tmp/ → documents/) = atomic rename (same volume) keeping today's retry/race semantics; copy/delete/head map to stream/unlink/stat. Key→path mapping must reject .. traversal.

Privacy tradeoff to decide at implementation time: S3 today exposes files by unguessable public URL. For local serving, parity (public-by-unguessable-key GET) is simplest and preserves split-origin <img> and AI-provider fetches; session-authenticated reads would break <img> in split-origin deployments and complicate AI receipt fetching. Recommend v1 = unguessable-key parity, with signed view tokens as a follow-up.

Milestones

M1 — Storage abstraction + local driver + config

• lib/storage/ interface + S3 driver (move existing storage.ts logic) + local driver (fs/promises, size/type guards, traversal protection).
• env.ts: UPLOADS_DRIVER (s3|local, default s3) + UPLOADS_DIR; superRefine allows PUBLIC_ENABLE_EXPENSE_DOCUMENTS=true with either full S3_UPLOAD_* or a valid UPLOADS_DIR. uploadsConfigured() becomes driver-aware.
• Refactor routes/upload.ts minting/validation/promotion/deletion helpers to delegate to the driver; outputs (uploadUrl/fileUrl) stay shape-identical so the tRPC layer and web client are unchanged.

M2 — API upload/serve routes + nginx

• PUT /uploads/<key> (auth + signed key claims, mirroring the staged-document JWT pattern) and GET /uploads/<key> on the Hono app.
• Add /uploads to nginx.web.conf proxy list (same-origin compose deployment).
• Local dev can drop MaxIO in compose.dev.yaml; update compose.yaml / compose.dokploy.yaml with an uploads_data volume mounted at UPLOADS_DIR.

M3 — Server read paths become driver-aware

• Replace getS3Object usages (export readers, import validation, profile-image validation) with the driver's getObject/headObject.
• Receipt extraction (lib/receipt-actions.ts): in local mode the AI provider cannot necessarily fetch the API URL — fetch bytes via the driver and pass them to the provider (base64/bytes) instead of a URL; keep the URL passthrough for S3.

M4 — S3↔local backup/migration CLI (the issue's second ask)

• bun-runnable script (e.g. apps/api/scripts/migrate-uploads.ts): enumerate ExpenseDocument + Account.image, download from source driver, write to destination driver, optionally rewrite stored URLs (with --dry-run and --rewrite). Since both drivers share one interface, S3→local, local→S3, and S3→S3 fall out of the same code.
• Document backing up the uploads volume alongside postgres_data.

M5 — Tests + docs

• Local driver unit tests (write/read/head/copy/delete/promote, traversal rejection, size enforcement); mirror s3-document-reader.test.ts.
• Update upload.test.ts for driver selection.
• Update README.md, docs/deployment.md, .env.example, container.env.example, all compose files.

Risks / notes

• Multi-replica deployments: a per-host volume only works for single API replica; S3 remains the right choice when scaling out. Call this out in docs.
• Legacy URLs: existing DB rows keep S3 URLs until the migration script rewrites them; M4 is also the S3→local path requested here.
• Rate/limits: the API upload route must enforce the same size limits (isExpenseDocumentSizeWithinLimit, MAX_PROFILE_IMAGE_SIZE) and membership checks the presign path does today.

This is actionable and self-contained — ready to start with M1 when the maintainer gives the go-ahead.

Task list (3/4 completed)

• Read issue [Idea] Local file uploads #86 and gather context
• Explore codebase architecture relevant to local file uploads
• Produce structured plan for addressing the issue
• Post plan via report_progress

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using openai-compatible/deepseek-v4-flash-free ｜ 𝕏}

[pullfrog]

Local file uploads (#86) is fully implemented on branch pullfrog/86-local-file-uploads (4 signed commits).

What changed

1. Storage driver abstraction (apps/api/src/lib/storage/): a unified UploadDriver interface with two implementations — s3.ts (existing S3-compatible backend) and local.ts (filesystem under UPLOADS_DIR, default /uploads, with .meta sidecars for content-type/size, traversal guards, and ObjectNotFoundError/ObjectTooLargeError). lib/storage.ts was replaced by the driver factory.
2. Upload/GET routes (apps/api/src/routes/uploads.ts): PUT /uploads/:key (HMAC-sealed token auth binding key/content-type/max-size, 413 on oversize) and GET /uploads/:key (immutable, long-cache; skipped when the S3 driver is active). Mounted in app.ts with CORS PUT; nginx proxies /uploads/ (client_max_body_size 10m, buffering off).
3. Consumers routed through the driver: routes/upload.ts mint/promote/delete flows, the expense-document export reader, and receipt-actions.ts (local mode fetches bytes server-side for the AI provider instead of requiring a public S3 endpoint).
4. Wiring/deploy: UPLOADS_DRIVER (default s3) + UPLOADS_DIR env schema (superRefine accepts S3 set OR local); compose.yaml / compose.dokploy.yaml add an uploads_data volume; .env.example/container.env.example updated.
5. Migration CLI (apps/api/scripts/migrate-uploads.ts): copies every stored object (expense documents + profile images) between the two backends with --dry-run / --rewrite (rewrite DB URLs to the destination backend). Documented in README (Option B: local storage) and docs/deployment.md.
6. Tests: local.test.ts (12), uploads.test.ts (6), env.test.ts uploads block (8), updated s3-document-reader.test.ts and receipt-actions.test.ts. All 138 affected tests pass; typecheck/lint/format green.

Verification: full API suite was run on both this branch and main under identical conditions — both show the same 9 failed files / 112 failures (DB ECONNREFUSED because no Postgres is running in this environment, plus 22 pre-existing api.test.ts failures), confirming zero regressions.

Task list (5/5 completed)

• M1: storage driver abstraction (types, s3, local, index) + env + routes/upload.ts refactor + consumers
• M2: PUT/GET /uploads routes + token auth + nginx + compose + env examples
• M3: export reader, receipt-actions local-mode byte fetch, profile-image validation via driver
• M4: S3<->local migration script + docs (README, deployment)
• M5: tests (local driver, upload routes, env schema) + typecheck/lint/format green

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using openai-compatible/deepseek-v4-flash-free ｜ 𝕏}