Configure environment and secrets for Astro

Summary

Configure environment variables and secrets for an Astro app on Ample. Values passed with --env or --env-file are stored encrypted and injected at runtime; the platform never prints them and ample.toml declares only variable names. The fixture proves delivery by reporting whether the secret is set without echoing it.

Prerequisites

• Code that reads configuration from the process environment
• The secret values at hand for --env or an env file
• An Ample account token with servers:write

Tested Configuration

• Template: node-22
• Runtime: node
• Size: s-1vcpu-1gb
• Install: npm install
• Build: npm run build --if-present
• Start: npm run start

Workflow Steps

1. Declare, do not commit
   In ample.toml declare SMTP_KEY = { secret = true } style entries; never put literal secrets in the manifest.
2. Pass values on deploy
   Use --env KEY=value (repeatable) or --env-file .env.production; values are encrypted at rest and reused on redeploys.
   ample deploy . --name --public --env CANARY_SECRET=...
3. Confirm without echoing
   Expose a route (/config) that reports secret=set or secret=missing, never the value.
4. 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 --kind build

Example

• Astro secret probe canary
  /config reports secret=set for an --env value delivered encrypted.
  Source Reference: tests/deploy-canaries/astro-postgres-app

Success Checks

• App sees the configured variable without exposing it:
  • Kind: http_get
  • Path: /config
  • Expect: secret=set

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.
• Plain env in the API request is rejected; only the encrypted path is supported.
• Rotating a secret requires a redeploy with the new value.

Cost Estimate

• Currency: USD
• Monthly Amount: 5.0
• Basis: Size prices from pricing.toml (loaded by the API) at build revision 1ac5595375130d45290090e82ed0f554ccd45405-dirty
• Components:
  • Name: app server
  • Size: s-1vcpu-1gb
  • Quantity: 1.0
  • Monthly Amount: 5.0
• Note: Apps and managed databases auto-pause when idle; the estimate is the always-on monthly price of the tested sizes. Plan quotas and budgets apply.

Evidence Summary

• Kind: canary_run
• Summary: Astro server endpoints (node adapter, standalone) using pg with an auto-provisioned managed PostgreSQL database: /db reported postgres=ok and /config confirmed the encrypted secret.
• Observed At: 2026-09-20T01:42:25Z
• Implementation Revision: 199ff1dfd52683832ae75d3f98b53a7a4bff7f96-dirty (CLI e3181f5)
• Expires At: 2027-03-19T01:42:25Z
• Scope:
  • CLI Version: 0.1.20
  • Platform: hosted-beta
  • Template: node-22

Next Actions

1. Browse the catalog index
   • Method: GET
   • Relative Path: /v1/catalog
2. Search published recipes by intent, stack and constraints
   • Method: POST
   • Relative Path: /v1/catalog/search
   • Parameters:
     • Body: {"limit":5,"query":"Configure environment and secrets for Astro"}
3. Prepare a side-effect-free deployment plan for an authorized project
   • Method: POST
   • Relative Path: /v1/catalog/plan
   • Parameters:
     • Body: {"inputs":{},"projectId":"","recipeId":"page:guides:astro:configuration-secrets","recipeRevision":"r1"}
4. Read the existing agent authentication setup
   • Method: GET
   • Relative Path: /mcp/setup
5. Browse Astro
   • Method: GET
   • Relative Path: /v1/catalog/nodes/stack%3Aframework-astro
6. Browse Configure deployment
   • Method: GET
   • Relative Path: /v1/catalog/nodes/intent%3Aconfigure-deployment
7. Browse Public web service
   • Method: GET
   • Relative Path: /v1/catalog/nodes/pattern%3Apublic-web-service