How to Configure S3 Asset Storage for OpenMAIC Deployments

You can configure S3 asset storage for OpenMAIC deployments by setting the ASSET_S3_BUCKET environment variable, which instructs the framework to lazily instantiate an S3AssetByteStore that persists assets to Amazon S3 without requiring any code changes.

The THU-MAIC/OpenMAIC repository implements a persistence abstraction layer that supports both local disk and cloud object storage backends. By leveraging environment variables, you can configure S3 asset storage for OpenMAIC deployments across Vercel, Docker, Kubernetes, or bare-metal servers while maintaining a declarative configuration approach.

Required Environment Variables

OpenMAIC detects S3 configuration through specific environment variables defined in lib/persistence/asset-byte-store.ts. When ASSET_S3_BUCKET is present, the factory function lazyAssetByteStore() creates an S3-backed store instead of the default local implementation.

Set these variables to enable AWS S3 storage:

• ASSET_S3_BUCKET – The name of your existing S3 bucket (e.g., my-openmaic-assets). This triggers the S3 storage path.
• AWS_ACCESS_KEY_ID – Your AWS access key.
• AWS_SECRET_ACCESS_KEY – Your AWS secret key.
• AWS_REGION – The AWS region where your bucket resides (e.g., us-east-1).

The S3 client uses the standard AWS SDK lookup chain, so credentials can also be provided via IAM instance profiles or ~/.aws/credentials files rather than explicit environment variables.

Configuring S3-Compatible Services

For MinIO, LocalStack, or other S3-compatible services, you must specify additional endpoint parameters. These are passed directly to the underlying S3Client constructor in packages/@openmaic/storage/src/asset/s3-bytes.ts.

Add these optional variables:

• S3_ENDPOINT – Custom endpoint URL (e.g., http://minio.local:9000).
• S3_FORCE_PATH_STYLE – Set to true for services that do not support virtual-hosted style buckets.

Deployment Configuration Examples

Local Development with dotenv

Create a .env file in your project root for local development:

ASSET_S3_BUCKET=my-openmaic-assets
AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
AWS_REGION=us-east-1

MinIO or LocalStack Configuration

For testing with a local MinIO instance:

ASSET_S3_BUCKET=openmaic-test
S3_ENDPOINT=http://minio.local:9000
S3_FORCE_PATH_STYLE=true
AWS_ACCESS_KEY_ID=minio_key
AWS_SECRET_ACCESS_KEY=minio_secret
AWS_REGION=us-east-1

Docker Compose Setup

Deploy to production with Docker Compose by injecting environment variables:

services:
  openmaic:
    image: ghcr.io/thu-maic/openmaic:latest
    environment:
      - ASSET_S3_BUCKET=maic-prod
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
      - AWS_REGION=eu-west-1

Programmatic Verification

You can verify the active store implementation at runtime:

import { lazyAssetByteStore } from '@/lib/persistence/server-provider';

// The store initializes as S3AssetByteStore when ASSET_S3_BUCKET is set
const assetStore = await lazyAssetByteStore(process.env.ASSET_S3_BUCKET, true);
console.log('Asset store type:', assetStore.constructor.name);

Implementation Details

The S3 integration relies on two key components in the OpenMAIC codebase.

lib/persistence/asset-byte-store.ts validates the ASSET_S3_BUCKET variable and manages the lifecycle of the byte store. It implements lazy loading — the AWS SDK is only imported the first time an asset operation is invoked. This means deployments that never touch assets run without the optional AWS SDK dependency, reducing cold start times and bundle size.

packages/@openmaic/storage/src/asset/s3-bytes.ts contains the S3AssetByteStore class, which implements the asset storage interface using S3. It handles binary put, get, and delete operations, along with presigned URL generation for temporary access. The class accepts the optional S3_ENDPOINT and S3_FORCE_PATH_STYLE parameters to support non-AWS object storage services.

Summary

• Set ASSET_S3_BUCKET to enable S3 storage; otherwise, OpenMAIC defaults to local disk.
• Use standard AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) or rely on IAM instance profiles.
• Configure S3_ENDPOINT and S3_FORCE_PATH_STYLE when using MinIO, LocalStack, or other S3-compatible APIs.
• Lazy loading ensures the AWS SDK is only imported when asset operations occur, keeping lightweight deployments fast.
• No code changes are required to switch storage backends—only environment variable updates.

Frequently Asked Questions

How does OpenMAIC handle AWS credentials when running on EC2 or EKS?

When deployed to AWS infrastructure, OpenMAIC follows the standard AWS SDK credential chain. If you omit AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, the S3AssetByteStore automatically retrieves temporary credentials from the EC2 instance profile or EKS IAM Roles for Service Accounts (IRSA), eliminating the need to manage static keys in production.

Can I use OpenMAIC without installing the AWS SDK?

Yes. The AWS SDK is an optional dependency. According to the source code in lib/persistence/asset-byte-store.ts, the SDK is loaded lazily—only when ASSET_S3_BUCKET is set and an asset operation is actually invoked. Deployments using only local storage never import the AWS libraries, keeping bundle sizes smaller.

What S3 operations does OpenMAIC support?

The S3AssetByteStore class in packages/@openmaic/storage/src/asset/s3-bytes.ts implements the full asset persistence interface, including put for uploads, get for downloads, delete for removal, and presigned URL generation for temporary public access. These operations cover all standard asset management needs for images, videos, and PDFs.

How do I migrate existing local assets to S3?

OpenMAIC does not include a built-in migration utility. To migrate, write a script that reads assets from your local disk using the file-system provider, then writes them to S3 using the S3AssetByteStore methods. Once migrated, set ASSET_S3_BUCKET and restart your deployment to point new requests to the S3 backend.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}