Configure S3-compatible access for Express

Summary

Configure S3-compatible access for a Express app on Ample. Create a bucket with ample bucket create, pass its endpoint, region, bucket name and keys as encrypted environment variables, and use @aws-sdk/client-s3 with forcePathStyle: true. The app writes and reads objects through the S3-compatible endpoint; the bucket stays private.

Prerequisites

• An S3 client in the app (@aws-sdk/client-s3 with forcePathStyle: true) reading S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY
• A bucket created with ample bucket create and its credentials from ample bucket credentials
• An Ample account token with servers:write and buckets:read

Workflow Steps

1. Create the bucket
   Create it once and keep the issued credentials out of the repository. Command: ample bucket create --name

2. Configure the client with path-style addressing
   Use @aws-sdk/client-s3 with forcePathStyle: true; virtual-host addressing is not verified.

3. Deploy with the credentials as encrypted env
   Pass the five S3_* variables with --env; they are stored encrypted and reused on redeploys. Command: ample deploy . --name --public --env S3_ENDPOINT=... --env S3_REGION=... --env S3_BUCKET=... --env S3_ACCESS_KEY_ID=... --env S3_SECRET_ACCESS_KEY=...

4. Test through the app
   Expose a route (/storage) that writes then reads an object and reports s3=ok.

5. Verify
   Fetch the live URL and run the success checks below. On failure read the build log, then the runtime log, fix the cause and deploy again; do not blind-retry. Command: ample logs --kind build

Success Checks

• Object write and read succeed
  Kind: http_get
  Path: /storage
  Expect: s3=ok

Limitations

• Verified on the node-22 template at s-1vcpu-1gb; other templates and sizes are not verified by this recipe.
• Region, compliance attestations and request-duration limits are unknown and not claimed.
• Apps auto-pause when idle and wake on the next request; always-on is an operator setting, not a plan feature.
• PutObject and GetObject with path-style addressing are verified; multipart upload, listing, presigned URLs and lifecycle rules are not verified.
• Bucket credentials are passed as encrypted environment variables; the catalog never creates the bucket for you (use ample bucket create).
• Storage is allocation-priced per bucket quota and capped by the account plan.

Examples

• Express bucket canary
  Write and read an object with the injected credentials.
  Source: tests/deploy-canaries/express-bucket-uploads

Cost Estimate

• Currency: USD
• Monthly Amount: 5.0
• Components:
  • App server: size s-1vcpu-1gb, quantity 1.0, monthly amount: 5.0
• Note: Compute only. Buckets are allocation-priced per quota and capped by the plan.