## Configure environment and secrets for Express

### Summary
Configure environment variables and secrets for an Express 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 the variable names.

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

### Workload
Configure environment and secrets

### Framework
Express

### Test Configuration
#### Template
- node-22
#### Runtime
- node
#### Size
- s-1vcpu-1gb
#### Install
```bash
npm install
```
#### Build
```bash
npm run build --if-present
```
#### Start
```bash
node server.js
```

### Input Schema
```json
{
    "type": "object",
    "properties": {
        "env": {
            "type": "array",
            "items": {
                "type": "string",
                "pattern": "^[A-Z][A-Z0-9_]*=.*$"
            },
            "maxItems": 50,
            "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"
        }
    },
    "required": ["env", "name", "path"],
    "additionalProperties": false
}
```

### 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 re-used on redeploys.
   ```bash
   ample deploy . --name  --public --env DATABASE_URL=postgres://...
   ```
3. **Confirm without echoing**  
   Expose a route that reports which variables are set (host names, not values) and check it.
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.
   ```bash
   ample logs  --kind build
   ```

### Success Checks
- Check that the app sees the configured variable without exposing it.  
  **Kind**: http_get  
  **Path**: /db  
  **Expect**: secret=false

### 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

### Evidence Summary
- **Kind**: canary_run  
  **Summary**: A supplied DATABASE_URL was delivered as an encrypted environment variable; the app saw the configured host and the secret was never echoed by the platform.  
  **Observed At**: 2026-09-19T23:55:33Z  
  **Scope**:  
  - **cliVersion**: 0.1.20  
  - **platform**: hosted-beta  
  - **template**: node-22

- **Kind**: canary_run  
  **Summary**: Express app with npm install and npm run start deployed on the node-22 template; the public URL served the expected response.  
  **Observed At**: 2026-09-19T23:55:33Z  
  **Scope**:  
  - **cliVersion**: 0.1.20  
  - **platform**: hosted-beta  
  - **template**: node-22

### Next Actions
- **Browse the catalog index**  
- **Search published recipes by intent, stack and constraints**  
  **Method**: POST  
- **Prepare a side-effect-free deployment plan for an authorized project**  
  **Method**: POST  
- **Read the existing agent authentication setup**  
- **Browse Express**  
- **Browse Configure deployment**  
- **Browse Public web service**