Storage service

Amazon S3

The S3 integration connects your project to an Amazon S3 (or S3-compatible) bucket — with a shared, Dreambase-managed bucket or a dedicated one you provide — publishes the connection details as outputs, and exposes object read/write/list/delete and pre-signed URL functions, plus health checks and metrics.

Amazon S3 is one of the Storage service integrations. It handles its own webhook route:

POST/s3/webhook
Connect to an S3 (or S3-compatible) bucket

What it does

On DEPLOYMENT_CREATED the service resolves the credentials (shared or dedicated), verifies the bucket is reachable with a HeadBucket, and publishes the connection details — bucket, region, endpoint, accessKeyId, secretAccessKey, publicBaseUrl, prefix, and url — back to Dreambase as outputs. It does not create or provision the bucket.

Server type

  • shared — use the Dreambase-managed bucket (S3_SHARED_*), namespaced by an optional key prefix. No AWS setup required.
  • dedicated (default) — bring your own bucket and credentials.

S3-compatible providers

Set a custom endpoint to target DigitalOcean Spaces, Cloudflare R2, MinIO, or any other S3-compatible provider. The Addressing Style input controls path- vs virtual-hosted addressing; auto uses path-style whenever a custom endpoint is set (which most providers require) and virtual-hosted for AWS.

Inputs

InputApplies toDescription
serverTypeallEither shared or dedicated (default).
bucketdedicatedThe S3 bucket name.
regiondedicatedThe bucket's AWS region (default us-east-1).
accessKeyIddedicatedThe access key ID for the bucket.
secretAccessKeydedicatedThe secret access key. Accepts a {{env.KEY}} reference.
endpointdedicatedOptional custom endpoint for an S3-compatible provider.
forcePathStylededicatedAddressing style: auto (default), path, or virtual.
publicBaseUrldedicatedOptional CDN or custom domain objects are served from.
prefixallOptional key prefix all object keys are namespaced under.

Outputs

  • bucket, region, endpoint — where the bucket lives.
  • accessKeyId, secretAccessKey — credentials for consumers to use the bucket.
  • publicBaseUrl, prefix — CDN domain and key namespace, if any.
  • url — the base URL objects are served from.

Functions

Callable via a FUNCTION_CALL event:

  • listObjects — list objects under an optional prefix (paged via a continuation token).
  • putObject — upload an object from content (text) or contentBase64 (binary), with an optional contentType. Returns the key and URL.
  • getObject — download an object; returns its content base64-encoded with its content type.
  • deleteObject — delete an object.
  • getSignedUrl — generate a pre-signed get or put URL with an expiresIn (default 3600s).

Metrics

On METRIC_UPDATE the service reports object_count and total_bytes from the first listing page (scoped to the key prefix) — a bounded gauge that never pages a huge bucket.

Events it handles

  • WEBHOOK_CHALLENGE — verify the webhook endpoint.
  • HEALTH_CHECK — HeadBucket to confirm the bucket is reachable.
  • METRIC_UPDATE — report object count and total bytes.
  • DEPLOYMENT_CREATED — verify the connection and publish the details as outputs.
  • DEPLOYMENT_DELETED — stop tracking the connection (the bucket and its data are left intact).
  • FUNCTION_CALL — run a named function.

Configuration

The service calls back into the API at DREAMBASE_API_URL (default http://localhost:3005) and runs on PORT 3013 locally. Shared-bucket credentials come from the S3_SHARED_* environment variables.