INFRASTRUCTURE

What it needs

• 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.)
• CDN: verified (The CDN host serves objects from published buckets. It does not front app compute and is not a cache or key-value store.)

PREREQUISITES

Before you start

• A bucket created with ample bucket create and published with ample bucket publish (its public URL is the CDN base)
• An S3 client in the app to upload assets under versioned keys
• An Ample account token with servers:write and buckets:write

TESTED CONFIGURATION

Exactly what was tested

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

STEP BY STEP

How to do it

1. Publish the bucket
   Publishing makes objects readable at the CDN URL; keep private data in a separate, unpublished bucket.

   ample bucket publish <bucket-name>
   

2. Upload versioned assets
   Use keys such as assets//file and set Cache-Control: public, max-age=31536000, immutable; change the version to invalidate.

3. Reference the CDN URL
   Pass S3_PUBLIC_URL to the app and build asset URLs from it.

   ample deploy . --name <app-name> --public --env S3_PUBLIC_URL=... --env S3_ENDPOINT=... --env S3_REGION=... --env S3_BUCKET=... --env S3_ACCESS_KEY_ID=... --env S3_SECRET_ACCESS_KEY=...
   

4. Verify delivery
   Fetch /asset-url for the asset URL, then fetch that URL: the CDN must return the asset.

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
   

EXAMPLES

Tested examples

• Express CDN assets canary (tests/deploy-canaries/express-cdn-assets): Versioned asset uploaded to a published bucket and served from the CDN URL.

SUCCESS CHECKS

How to know it worked

• asset URL resolves through the CDN (/asset-url on the live URL, expect https://cdn.)

LIMITATIONS

Know the limits

• 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.
• The CDN serves objects from a published bucket only; it does not front the app's own responses.
• Cache rules, purge and TTL control are not verified; the fixture sets Cache-Control on upload and versions asset keys instead.

COST

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.

EVIDENCE

Verification evidence

• canary_run on 2026-09-20T01:13:26Z at revision cc3d82057f1d5e9aa31f682cee71aabfbbbcaabe-dirty (CLI e3181f5): Express app uploaded a versioned, immutable-cached asset to a published bucket at startup; the CDN URL it returned served the asset publicly. (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)

EXECUTION

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 at export: current. Required scopes: servers:write, buckets:write.

NEXT ACTIONS

Typed next actions

• Browse the catalog index (GET /v1/catalog on the api origin; authentication not required, approval not required)
• Search published recipes by intent, stack and constraints (POST /v1/catalog/search on the api origin; authentication not required, approval not required)
• Prepare a side-effect-free deployment plan for an authorized project (POST /v1/catalog/plan on the api origin; authentication required, approval not required)
• Read the existing agent authentication setup (GET /mcp/setup on the api origin; authentication not required, approval not required)
• Browse Express (GET /v1/catalog/nodes/stack%3Aframework-express on the api origin; authentication not required, approval not required)
• Browse Add CDN (GET /v1/catalog/nodes/intent%3Aadd-cdn on the api origin; authentication not required, approval not required)
• Browse Versioned static assets (GET /v1/catalog/nodes/pattern%3Aversioned-static-assets on the api origin; authentication not required, approval not required)

Actions describe possible next steps. They are typed data, not commands, and grant no permission. Public discovery never provisions anything; planning requires your own authenticated token and approval happens in your client.