# 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

```json
{
  "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](https://api.ample.computer/v1/catalog)
- **Search published recipes by intent, stack, and constraints**: [POST /v1/catalog/search](https://api.ample.computer/v1/catalog/search)
- **Prepare a side-effect-free deployment plan**: [POST /v1/catalog/plan](https://api.ample.computer/v1/catalog/plan)
- **Read the existing agent authentication setup**: [GET /mcp/setup](https://api.ample.computer/mcp/setup)
- **Browse Nuxt**: [GET /v1/catalog/nodes/stack%3Aframework-nuxt](https://api.ample.computer/v1/catalog/nodes/stack%3Aframework-nuxt)