# Configure S3-compatible access for FastAPI

## Summary
Configure S3-compatible access for a FastAPI app on Ample. Create a bucket with `ample bucket create`, pass its endpoint, region, bucket name and keys as encrypted environment variables, and use boto3 with Config(s3={'addressing_style': 'path'}). The app writes and reads objects through the S3-compatible endpoint; the bucket stays private.

## Infrastructure requirements
- Verified compute (Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.)
- Verified S3-compatible object storage (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 (boto3 with Config(s3={'addressing_style': 'path'})) 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: `python-3.12`
- runtime: `python`
- size: `s-1vcpu-1gb`
- install: `python3 -m pip install --target .ample/python -r requirements.txt`
- start: `PYTHONPATH=.ample/python:${PYTHONPATH:-} python3 run.py`

## 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 boto3 with Config(s3={'addressing_style': 'path'}); 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 --start "python3 run.py" --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.

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

## Tested examples
- **FastAPI bucket canary** (tests/deploy-canaries/fastapi-bucket-uploads): Write and read an object with the injected credentials.

## Success checks
- object write and read succeed (`/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)`: FastAPI app using boto3 (path-style addressing) with injected bucket credentials: put_object then get_object returned s3=ok. (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.