Buckets

Define file storage, select a provider profile, and control object size, media types, and visibility.

A bucket stores files such as product images and invoices. Its definition gives the bucket a stable identity and sets its storage rules.

Pre-setup

Use MinIO in local Docker for development. Start from an existing RELKIT app and a running Docker daemon.

Install the storage integration

From this guide’s application/package root, install only its selected requirements:

bun add @relkit/docker@0.7.12 @relkit/s3@0.7.12

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in dependencies; build/type tooling belongs in devDependencies. Installing an adapter does not supply its optional SDK peers or enable the feature’s configuration.

Configure the assets profile

/** Local MinIO supplies connection values without application-owned credentials. */
import { defineApp, defineEnv } from "@relkit/app/config";
import { docker } from "@relkit/docker";
import { s3 } from "@relkit/s3";

export default defineApp({
  env: defineEnv({}),
  bucket: { assets: docker(s3()) },
  defaults: { bucket: "assets" },
});

Buckets with profile: "assets", or no explicit profile, now select local MinIO. Docker supplies its endpoint and credentials; no S3 secrets belong in defineEnv for this local path. For an existing S3 service, follow connected storage instead.

Check and start after defining the bucket

Check Docker before continuing. After adding the resource and its service registration, run from the app root:

docker version
bun run check
bun run typecheck
bun run dev

check validates the graph; it starts no containers. dev starts only Docker recipes used by that graph, waits for readiness, and binds their generated connection values. An unused profile alone does not start a container. Keep the server running and use bun run relkit local status in another terminal to inspect the services. Local Docker covers detached startup and stopping services while retaining their volumes.

This bucket accepts images and JSON files, with a maximum size of 5 MB per object:

/** Declares private JSON/image assets with a five-million-byte limit for validated upload handlers. */
import { defineBucket } from "@relkit/app/buckets";

const assets = defineBucket({
  id: "assets.objects",
  profile: "assets",
  visibility: "private",
  maxObjectBytes: 5_000_000,
  allowedContentTypes: ["application/json", "image/*"],
});

export default assets;

id identifies this bucket in RELKIT. Keep it stable when moving or renaming the file.

profile selects the storage connection named assets in your application configuration. That configuration determines which provider stores the files.

visibility controls object visibility. Authentication for an upload endpoint is configured separately.

Configure storage

Define or scaffold a bucket: provider selection, limits, and validation.

Configure local storage: install the S3 integration and run MinIO through Docker.

Write objects: dependencies, file validation, and storage operations.

Read files and create download links: reads, listing, deletion, and signed URLs.

Ready to configure your own provider? Continue with Configure local storage.