Configuration

Rack Gateway is configured primarily through environment variables. This section covers all configuration options grouped by concern.

Configuration Sources

Rack Gateway uses mise for environment variable management:

• mise.toml - Project defaults (committed to git)
• mise.local.toml - Local overrides (gitignored)

No .env Files

This project does not use .env files. All environment configuration goes through mise for consistency.

Quick Reference

Environment Variables

Complete reference of all environment variables.

OAuth Setup

Google Workspace OAuth configuration guide.

Sessions

Session policies and timeout configuration.

Security Settings

MFA, sessions and deploy approvals in the Settings page.

Essential Configuration

For production deployment, you must configure:

1. OAuth Authentication

mise.local.toml

[env]
GOOGLE_CLIENT_ID = "your-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET = "your-client-secret"
GOOGLE_ALLOWED_DOMAIN = "your-company.com"

See OAuth Setup for detailed instructions.

2. Database

[env]
DATABASE_URL = "postgres://user:pass@host:5432/rack_gateway?sslmode=require"

Or, without DATABASE_URL, the standard libpq variables:

[env]
PGHOST = "your-db-host"
PGPORT = "5432"
PGUSER = "rack_gateway"
PGPASSWORD = "your-password"
PGDATABASE = "rack_gateway"

3. Security Keys

[env]
APP_SECRET_KEY = "your-32-byte-random-key"  # Generate with: openssl rand -hex 32
COLUMN_ENCRYPTION_KEY = "your-column-key"     # Generate once with: openssl rand -base64 32

COLUMN_ENCRYPTION_KEY encrypts stored TOTP seeds and the Slack token, so keep it and back it up. See Column Encryption.

4. Convox Rack Connection

[env]
RACK_HOST = "https://api.rack.convox.cloud"
RACK_TOKEN = "your-rack-api-token"
RACK_ALIAS = "production"

Configuration Categories

Category	Purpose
Environment Variables	Complete reference of all options
OAuth Setup	Google Workspace authentication
Sessions	Session timeout and policies
Settings	MFA enforcement, timeouts, destructive actions, deploy approvals
Security Hardening	Production security configuration
Email	Postmark email configuration

Development vs Production

Development Defaults

Development mode (DEV_MODE=true) only exists in builds compiled with the testbypass Go build tag, which task dev and the Docker development and E2E stacks use. In development mode, Rack Gateway:

• Uses non-secure cookies (no HTTPS required)
• Auto-generates APP_SECRET_KEY if missing (COLUMN_ENCRYPTION_KEY is never generated: it is required in every mode)
• Runs database migrations on startup (production never does: run rack-gateway-api migrate)
• Logs emails to stdout instead of sending them, unless POSTMARK_API_TOKEN is set
• Connects to mock services on localhost

The published Docker image is built without the tag, and refuses to start with DEV_MODE or any other test bypass set.

Production Requirements

For production, run the published image (or an image built with task docker), serve it over HTTPS (cookies are always Secure), and set:

• APP_SECRET_KEY (secure random value)
• COLUMN_ENCRYPTION_KEY (generated once and backed up)
• AUDIT_HMAC_SECRET (secure random value)
• OAuth credentials (real Google Workspace)
• DOMAIN (the gateway’s hostname)
• Database URL (real PostgreSQL)
• Rack credentials (real Convox rack)

Database-Backed Settings

Some settings can be configured via the web admin UI and stored in the database:

Setting	Environment Variable	Database Setting
Session timeout	RGW_SETTING_SESSION_TIMEOUT_MINUTES	session_timeout_minutes
Require MFA	RGW_SETTING_MFA_REQUIRE_ALL_USERS	mfa_require_all_users
Step-up window	RGW_SETTING_MFA_STEP_UP_WINDOW_MINUTES	mfa_step_up_window_minutes
Trusted device TTL	RGW_SETTING_MFA_TRUSTED_DEVICE_TTL_DAYS	mfa_trusted_device_ttl_days

Precedence: An environment variable takes priority over the database, and makes the setting read-only in the UI.

Next Steps

• Start with Environment Variables for the complete reference
• See OAuth Setup to configure authentication
• Review Production Checklist before going live