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 (for the first deploy; later deploys can go through the gateway)
• Google OAuth client configured (see OAuth Setup)
• A PostgreSQL database with the audit roles, an admin user and an app user (see Database Setup)
• A private network to reach it: the gateway service is internal: true (see Private Network)

Deployment Steps

1. Set required environment variables

   convox env set -a rack-gateway \
     DOMAIN=gateway.example.com \
     APP_SECRET_KEY=$(openssl rand -base64 32) \
     AUDIT_HMAC_SECRET=$(openssl rand -base64 32) \
     COLUMN_ENCRYPTION_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 \
     DATABASE_URL=postgres://rack_gateway_app:...@db-host:5432/rack_gateway \
     ADMIN_DATABASE_URL=postgres://rack_gateway_admin:...@db-host:5432/rack_gateway

   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).

   Caution

   Set COLUMN_ENCRYPTION_KEY once and back it up. It encrypts TOTP seeds and the Slack token, so changing or losing it means users re-enroll TOTP and Slack is reconnected. See Column Encryption.

2. (Optional) Configure audit anchors

   convox env set -a rack-gateway \
     AUDIT_ANCHOR_BUCKET=your-worm-bucket \
     AUDIT_ANCHOR_CHAIN_ID=production

   The gateway’s IAM role (the IAM_ROLE_ARN annotation in convox.yml) needs to write to the bucket. See S3 WORM Storage.

3. Build, migrate, promote

   The gateway never migrates on startup, so convox deploy alone would start a release against an old schema. Build the release, migrate with it, then promote it:

   convox build -a rack-gateway --description "rack-gateway vX.Y.Z"   # prints the release ID
   convox run admin ./rack-gateway-api migrate -a rack-gateway --release <release-id>
   convox releases promote <release-id> -a rack-gateway

4. Verify

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

   Then sign in as one of the ADMIN_USERS and enroll MFA.

Environment Variables

Required

Variable	Description
DOMAIN	Gateway domain (used for OAuth redirects)
APP_SECRET_KEY	Session/CSRF secret (at least 32 bytes)
AUDIT_HMAC_SECRET	Audit hash chain secret (at least 32 bytes)
DATABASE_URL	The app user’s connection string
ADMIN_DATABASE_URL	The admin user’s connection string, for the admin service
COLUMN_ENCRYPTION_KEY	Encrypts stored TOTP seeds and the Slack token (openssl rand -base64 32)
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
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

Use an external PostgreSQL (for example RDS) set up as in Database Setup: the gateway service connects as the app user (DATABASE_URL), and the admin service as the admin user (RGW_DATABASE_URL=${ADMIN_DATABASE_URL} in convox.yml).

Running Migrations

Use the admin service in convox.yml for database tasks, against the release you’re about to promote:

convox run admin ./rack-gateway-api migrate -a rack-gateway --release <release-id>

migrate needs COLUMN_ENCRYPTION_KEY like the server does (convox.yml shares it with every service).

Later Deploys

Once the gateway runs, deploy it through itself with the rack-gateway CLI. From the repository root:

./scripts/bump-version.sh patch     # pins convox.yml to the new image tag
./scripts/deploy.sh <rack>          # build, migrate against the new release, promote

scripts/deploy_all.sh runs deploy.sh for each rack in its RACKS list in turn (edit the list for your racks).

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
• The image pinned to an immutable release tag (docker.io/docspringcom/rack-gateway:vX.Y.Z), never :latest

Keep the manifest in sync with your deployment.