Configure object storage

The Asset Service talks to storage through one StorageAdapter, so switching backends is configuration only. StackRivet ships three backends: local disk (development), S3-compatible (MinIO, AWS S3, …) and Aliyun OSS. Exactly one is active at a time.

The shared configuration block:

stackrivet:
  asset:
    storage-type: local            # local | s3 | aliyun_oss
    max-file-size: 104857600       # bytes (100 MB)
    allowed-extensions: [jpg, jpeg, png, pdf, xlsx, csv]
    signed-url-ttl: 300            # seconds

Secrets are injected from environment variables and must never be committed.

Local (development)

The default. Files are written to local disk — fine for development, not for production (they don’t survive a container restart or scale-out).

stackrivet:
  asset:
    storage-type: local

Set STACKRIVET_STORAGE_TYPE=local (or leave the default).

S3-compatible (MinIO, AWS S3)

Use this for MinIO locally or AWS S3 (and other S3-compatible stores). For local testing, the server’s docker-compose.yml includes a minio service:

docker compose up -d minio

Configuration:

stackrivet:
  asset:
    storage-type: s3
    s3:
      endpoint: ${STACKRIVET_S3_ENDPOINT}
      region: ${STACKRIVET_S3_REGION}
      access-key-id: ${STACKRIVET_S3_ACCESS_KEY}
      secret-access-key: ${STACKRIVET_S3_SECRET_KEY}
      path-style-access: true      # true for MinIO

Set STACKRIVET_STORAGE_TYPE=s3 and the STACKRIVET_S3_* variables. path-style-access: true is typical for MinIO.

Aliyun OSS

stackrivet:
  asset:
    storage-type: aliyun_oss
    s3:
      endpoint: ${STACKRIVET_ALIYUN_OSS_ENDPOINT}   # e.g. https://oss-us-west-1.aliyuncs.com
      region: us-west-1
      access-key-id: ${STACKRIVET_ALIYUN_OSS_ACCESS_KEY}
      secret-access-key: ${STACKRIVET_ALIYUN_OSS_SECRET_KEY}

Set STACKRIVET_STORAGE_TYPE=aliyun_oss and the STACKRIVET_ALIYUN_OSS_* variables.

Region requirements

The endpoint’s region must match the bucket’s region, or OSS returns AccessDenied. region and path-style-access apply to S3 only and are ignored by OSS. Both S3 and OSS are injected into the same stackrivet.asset.s3.* block — only the backend selected by storage-type is active.

Verify

After configuring, confirm the configuration and then run an upload round-trip:

• Use the CLI: stackrivet doctor to check that the selected storage type and required credentials are present (see the CLI reference).
• Then upload a file through the admin UI and check it lands in the bucket, then download it (the private-file download is permission-checked and uses a short-lived signed URL).

Common storage variables are listed in Configuration.