Convox Deployment

Rack Gateway deploys as a single Convox service that serves the API and the web UI. An optional admin service is included in convox.yml for running migrations or admin tasks.

Prerequisites

• Convox CLI authenticated against your rack
• Google OAuth client configured (see OAuth Setup)
• PostgreSQL database (Convox resource or external)

Deployment Steps

1. Set required environment variables

   convox env set \
     DOMAIN=gateway.example.com \
     APP_SECRET_KEY=$(openssl rand -base64 32) \
     GOOGLE_CLIENT_ID=your-client-id \
     GOOGLE_CLIENT_SECRET=your-client-secret \
     GOOGLE_ALLOWED_DOMAIN=example.com \
     ADMIN_USERS=admin@example.com \
     RACK_TOKEN=your-convox-rack-token

   Note

   If you’re not running inside the same Convox rack (or want to override), set RACK_HOST to the Convox API URL (e.g., https://api.rack.convox.cloud).

2. (Optional) Configure audit anchors

   convox env set \
     AUDIT_HMAC_SECRET=your-hmac-secret \
     AUDIT_ANCHOR_BUCKET=your-worm-bucket \
     AUDIT_ANCHOR_CHAIN_ID=production \
     AUDIT_ANCHOR_RETENTION_DAYS=400

3. Deploy

   convox deploy -a rack-gateway

4. Verify

   curl -s https://gateway.example.com/api/v1/health

Environment Variables

Required

Variable	Description
DOMAIN	Gateway domain (used for OAuth redirects)
APP_SECRET_KEY	Session/CSRF secret
GOOGLE_CLIENT_ID	OAuth client ID
GOOGLE_CLIENT_SECRET	OAuth client secret
GOOGLE_ALLOWED_DOMAIN	Allowed email domain
ADMIN_USERS	Comma-separated bootstrap admin emails
RACK_TOKEN	Convox rack API token

Recommended

Variable	Description
AUDIT_HMAC_SECRET	HMAC chain secret (required in production)
RACK_ALIAS	Short rack identifier
RACK_DISPLAY_NAME	Human-readable rack name

Optional

Variable	Description
RACK_HOST	Convox rack API URL (override)
POSTMARK_API_TOKEN	Email notifications
SLACK_CLIENT_ID	Slack integration
SLACK_CLIENT_SECRET	Slack integration

Tip

For the complete list, see Environment Variables.

Database Configuration

Using Convox PostgreSQL Resource

convox resources create postgres --name gateway-db
convox resources link gateway-db -a rack-gateway

Convox automatically sets DATABASE_URL for linked apps.

Using External PostgreSQL

convox env set DATABASE_URL=postgres://user:pass@host:5432/rack_gateway

Running Migrations

Use the admin service in convox.yml for database tasks:

convox run admin -- ./rack-gateway-api migrate -a rack-gateway

Convox Manifest

The repository ships a production-ready convox.yml that defines:

• gateway service (API + web UI)
• admin service (on-demand maintenance)
• CloudWatch retention via LOG_RETENTION_DAYS in appSettings

Keep the manifest in sync with your deployment.