# Configure S3-compatible access for Next.js

## Summary

Configure S3-compatible access for a Next.js 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 inside a dynamic route handler with forcePathStyle: true. The app writes and reads objects through the S3-compatible endpoint; the bucket stays private.

## Infrastructure requirements

- [Compute]: verified (Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.)
- [S3-compatible object storage]: verified (Buckets are S3-compatible with issued credentials; PutObject and GetObject are verified by canary. Other S3 operations are not verified.)

## Prerequisites

- An S3 client in the app (@aws-sdk/client-s3 inside a dynamic route handler 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 <name>` and its credentials from `ample bucket credentials <name>`
- An Ample account token with servers:write and buckets:read

## Exact tested configuration

- template: `node-22`
- runtime: `node`
- size: `s-1vcpu-1gb`
- install: `npm install`
- build: `npm run build --if-present`
- start: `npm run start`

## Steps

1. **Create the bucket.** Create it once and keep the issued credentials out of the repository.

```
   ample bucket create --name <bucket-name>
   ```
2. **Configure the client with path-style addressing.** Use @aws-sdk/client-s3 inside a dynamic route handler 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.

```
   ample deploy . --name <app-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 (/api/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.

```
   ample logs <deployment_id> --kind build
   ```

## Tested examples

- **Next.js bucket canary** (tests/deploy-canaries/next-bucket-uploads): Write and read an object with the injected credentials.

## Success checks

- object write and read succeed (`/api/storage` on the live URL, 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; the estimate below covers compute only.

## Cost estimate

Estimated 5.00 USD per month (size prices from pricing.toml at build revision a1b8c38919e59cd035ebabaced73cf84ece24371).
- app server x1 `s-1vcpu-1gb`: 5.00 USD

Compute only. Buckets are allocation-priced per quota and capped by the plan; see `ample usage`.

## Verification evidence

- canary_run on 2026-09-20T01:13:26Z at revision `cc3d82057f1d5e9aa31f682cee71aabfbbbcaabe-dirty (CLI e3181f5)`: Next.js route handler using @aws-sdk/client-s3 with injected bucket credentials: PutObject then GetObject returned s3=ok at request time. (expires 2027-03-19T01:13:26Z)
- canary_run on 2026-09-20T01:13:26Z at revision `cc3d82057f1d5e9aa31f682cee71aabfbbbcaabe-dirty (CLI e3181f5)`: ample bucket create issued credentials; PutObject and GetObject succeeded through the public S3 endpoint; publish exposed the object through the CDN host with an ETag; unpublish and delete cleaned up. (expires 2027-03-19T01:13:26Z)

Last verified: 2026-09-20T01:13:26Z

## Execution binding

MCP tool `ample_deploy` (registry `mcp:ample_deploy`), schema hash `876465fce906da0c` observed 2026-09-20T01:55:48.667900+00:00 at revision `199ff1dfd526`, binding state `current`, required scopes: servers:write, buckets:read.