Blob Storage

Procella stores checkpoint data (infrastructure state snapshots) in a blob storage backend. Two backends are supported: local filesystem and S3-compatible object storage.

Backend Selection

Set PROCELLA_BLOB_BACKEND to choose the backend:

Value	Backend	Use Case
local (default)	Local filesystem	Single-server development
s3	S3-compatible	Production, multi-replica

Local Filesystem

export PROCELLA_BLOB_BACKEND=local
export PROCELLA_BLOB_LOCAL_PATH=./data/blobs

Checkpoints are stored as files in the specified directory. The directory is created automatically if it doesn’t exist.

Caution

Local blob storage is not suitable for multi-replica deployments. Each replica would have its own local directory, and checkpoints written by one replica would be invisible to others. Use S3 for horizontal scaling.

S3-Compatible Storage

export PROCELLA_BLOB_BACKEND=s3
export PROCELLA_BLOB_S3_BUCKET=procella-checkpoints

Works with any S3-compatible object storage:

Provider	Configuration
AWS S3	Set PROCELLA_BLOB_S3_BUCKET, configure AWS credentials via standard methods
MinIO	Set PROCELLA_BLOB_S3_ENDPOINT=http://minio:9000 + static credentials
Cloudflare R2	Set PROCELLA_BLOB_S3_ENDPOINT to R2 endpoint + API credentials
DigitalOcean Spaces	Set PROCELLA_BLOB_S3_ENDPOINT + access keys

Custom Endpoint (MinIO, R2, etc.)

When PROCELLA_BLOB_S3_ENDPOINT is set, Procella uses path-style addressing and requires explicit credentials:

export PROCELLA_BLOB_BACKEND=s3
export PROCELLA_BLOB_S3_BUCKET=procella-checkpoints
export PROCELLA_BLOB_S3_ENDPOINT=http://minio:9000
export AWS_ACCESS_KEY_ID=minio
export AWS_SECRET_ACCESS_KEY=minio

AWS S3 (Standard)

When no custom endpoint is set, Procella uses the standard AWS SDK credential chain:

export PROCELLA_BLOB_BACKEND=s3
export PROCELLA_BLOB_S3_BUCKET=my-procella-bucket
# Credentials via AWS_ACCESS_KEY_ID/SECRET, IAM role, etc.

BlobStorage Interface

The blob storage layer implements a simple interface:

export interface BlobStorage {
  get(key: string): Promise<Uint8Array | null>;
  put(key: string, data: Uint8Array): Promise<void>;
  delete(key: string): Promise<void>;
  exists(key: string): Promise<boolean>;
}

Keys are opaque strings generated by the checkpoint service. The Delete operation is idempotent — deleting a non-existent key returns success.

MinIO in Docker Compose

The default Docker Compose configuration includes MinIO for local S3-compatible storage:

minio:
  image: minio/minio:RELEASE.2025-01-20T14-49-07Z
  command: server /data --console-address ":9001"
  environment:
    MINIO_ROOT_USER: minioadmin
    MINIO_ROOT_PASSWORD: minioadmin
  ports:
    - "9000:9000"   # S3 API
    - "9001:9001"   # Web console

minio-init:
  image: minio/mc:RELEASE.2025-01-17T23-25-50Z
  entrypoint: >
    /bin/sh -c "
    mc alias set local http://minio:9000 minioadmin minioadmin &&
    mc mb --ignore-existing local/procella-checkpoints
    "

The minio-init container automatically creates the procella-checkpoints bucket on first start. You can browse stored objects at http://localhost:9001.