File Storage

Nibchat supports three file storage backends for uploaded files. The default stores files directly in the database; two external backends are available for larger deployments.

Storage backends

Database BLOB (default)

No configuration needed. Uploaded files are stored as base64 data URLs in the files table alongside the rest of your data.

This is the right choice for small deployments where simplicity matters more than storage efficiency.

Local filesystem

environment:
  - FILE_STORAGE_PATH=/app/uploads
volumes:
  - nibchat-uploads:/app/uploads

Files are written to the specified directory as raw binary. Data URLs are reconstructed on the fly when files are read back. The directory is created automatically on startup if it does not exist.

Use this when you want to keep files out of the database but don't need cloud storage.

S3-compatible object storage

Works with AWS S3, Cloudflare R2, MinIO, Tigris, and any other S3-compatible service.

environment:
  - S3_BUCKET=my-nibchat-files
  - S3_REGION=auto                                        # or us-east-1, etc.
  - S3_ENDPOINT=https://...r2.cloudflarestorage.com       # omit for AWS
  - S3_ACCESS_KEY_ID=your-access-key
  - S3_SECRET_ACCESS_KEY=your-secret-key
  - S3_PRESIGN_TTL=3600                                   # optional, default 3600s

Files are stored in the bucket and served to the browser via short-lived presigned URLs — the bucket does not need to be public.

Provider priority

If both S3_BUCKET and FILE_STORAGE_PATH are set, S3 takes precedence.

File cleanup

When a conversation, session, or user is deleted — either from the chat UI or the admin dashboard — Nibchat automatically removes the associated files from whichever storage backend is active. There is no orphaned file accumulation.

Environment variables

Variable	Default	Description
FILE_STORAGE_PATH	—	Absolute path for local file storage. If unset, files are stored in the database.
S3_BUCKET	—	Bucket name. Setting this enables S3 storage and takes precedence over FILE_STORAGE_PATH.
S3_ENDPOINT	—	Custom endpoint URL for R2/MinIO/Tigris. Omit for AWS.
S3_REGION	auto	S3 region (e.g. us-east-1).
S3_ACCESS_KEY_ID	—	S3 access key.
S3_SECRET_ACCESS_KEY	—	S3 secret key.
S3_PRESIGN_TTL	3600	Presigned URL TTL in seconds.