Configure environment and secrets for Nuxt

Summary

Configure environment variables and secrets for a Nuxt 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

Input Schema

{
  "type": "object",
  "required": ["env", "name", "path"],
  "additionalProperties": false,
  "properties": {
    "env": {
      "type": "array",
      "maxItems": 50,
      "items": {
        "type": "string",
        "pattern": "^[A-Z][A-Z0-9_]*=.*$"
      },
      "description": "Encrypted environment variables as KEY=value; secret values are never stored in ample.toml"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 63,
      "pattern": "^[a-z0-9-]+$",
      "description": "App name (lowercase, digits and dashes)"
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "Project directory to deploy, or one service name from ample.toml"
    },
    "size": {
      "type": "string",
      "enum": ["s-1vcpu-256mb", "s-1vcpu-1gb", "s-1vcpu-2gb", "s-2vcpu-2gb", "s-2vcpu-4gb"],
      "description": "VM size; omit to let Ample pick a runtime-safe size"
    },
    "start": {
      "type": "string",
      "maxLength": 512,
      "description": "Start command override when detection cannot infer it (Python apps pass one explicitly)"
    }
  }
}

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.

   Command: ample deploy . --name --public --env CANARY_SECRET=...

3. Confirm without echoing: Expose a route (/api/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.

   Command: ample logs --kind build

Examples

Nuxt secret probe canary

Description: /api/config reports secret=set for an --env value delivered encrypted. Source Reference: tests/deploy-canaries/nuxt-postgres-app

Success Checks

• App sees the configured variable without exposing it:
  • Kind: http_get
  • Path: /api/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
• 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: Nuxt server routes using pg with an auto-provisioned managed PostgreSQL database: /api/db reported postgres=ok and /api/config confirmed an encrypted secret was delivered without echoing it.
• Observed At: 2026-09-20T01:42:25Z
• Expires At: 2027-03-19T01:42:25Z
• CLI Version: 0.1.20
• Platform: hosted-beta
• Template: node-22

Next Actions

• Browse the catalog index: GET /v1/catalog
• Search published recipes by intent, stack, and constraints: POST /v1/catalog/search
• Prepare a side-effect-free deployment plan: POST /v1/catalog/plan
• Read the existing agent authentication setup: GET /mcp/setup
• Browse Nuxt: GET /v1/catalog/nodes/stack%3Aframework-nuxt