---
title: Buckets
description: Define file storage, select a provider profile, and control object size, media types, and visibility.
pagination: false
sidebar:
  icon: hard-drive
---

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

> **Start here**
>
> Start with **[Upload product images](/guides/storage/upload-product-images)** for installation, an
> HTTP endpoint, and verification. For the complete option contract, see
> [`defineBucket`](/docs/api/buckets#definebucket).

## Pre-setup

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

1. **Install the storage integration**

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

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

    ```sh
    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.

2. **Configure the assets profile**

    > **Merge with your application**
    >
    > The root configuration helper is [`defineApp`](/docs/learn/concepts/application), not
    > `defineConfig`. Merge the capability entries below into your existing `relkit.config.ts`; keep its
    > ID, environment, profiles, and other settings. The empty `defineEnv({})` in a standalone example
    > means this local provider needs no application variables. Keep your existing environment contract.

    ```ts title="relkit.config.ts"
    /** 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](/docs/modules/storage/local-storage) instead.

3. **Check and start after defining the bucket**

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

    ```sh title="Terminal — application 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](/docs/modules/integrations/local-docker)
    covers detached startup and stopping services while retaining their volumes.

<span id="the-storage-api"></span>

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

```ts title="src/services/assets/buckets/assets.bucket.ts"
/** 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](/docs/modules/storage/define): provider selection, limits, and
validation.

[Configure local storage](/docs/modules/storage/local-storage): install the S3 integration and
run MinIO through Docker.

[Write objects](/docs/modules/storage/upload): dependencies, file validation, and storage
operations.

[Read files and create download links](/docs/modules/storage/read-delete): reads, listing,
deletion, and signed URLs.

<span id="try-it-in-your-app"></span>

Ready to configure your own provider? Continue with [Configure local storage](/docs/modules/storage/local-storage).