page:guides:express:configuration secrets

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

Workload

Configure environment and secrets

Framework

Express

Test Configuration

Template

Runtime

Size

Install

npm install

Build

npm run build --if-present

Start

node server.js

Input Schema

{
    "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.
    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.
    ample logs  --kind build

Success Checks

Limitations

Cost Estimate

Evidence Summary

Next Actions