Deployment

Rack Gateway can be deployed using Docker, Convox, or any container orchestration platform. This section covers deployment options, infrastructure setup, and production best practices.

Deployment Options

DockerRun with Docker Compose or standalone containers.

ConvoxDeploy on Convox racks (recommended for production).

Private NetworkDeploy behind Tailscale or VPN for maximum security.

TerraformInfrastructure as code for AWS resources.

Architecture Overview

Deployment Model

Rack Gateway follows a single-tenant, per-rack deployment model:

Aspect	Description
One gateway per rack	Each Convox rack has its own gateway instance
No multi-tenancy	Gateway manages exactly one rack
Own database	Each gateway uses its own PostgreSQL database (one server can host several)
Private network	Recommended: Deploy behind Tailscale/VPN

Prerequisites

Before deploying, ensure you have:

Required

• PostgreSQL (16 is what CI runs) - Database for users, tokens, audit logs
• Google Workspace - OAuth provider for authentication
• Domain name - For gateway API and web UI

Recommended

• Tailscale - Private network access
• Postmark - Email notifications
• Slack - Real-time notifications
• S3 bucket - WORM storage for audit anchoring

Quick Start Path

1. Set up infrastructure

   Create PostgreSQL database and S3 bucket (if using audit anchoring).

2. Configure OAuth

   Create Google OAuth client with correct redirect URIs.

3. Set environment variables

   Configure all required environment variables for your deployment method.

4. Deploy

   Choose Docker for testing, Convox for production.

5. Verify

   Check /api/v1/health and log in to the web UI.

6. Harden

   Follow the production checklist for security hardening.

Environment Configuration

All deployments use the same environment variables. Key categories:

Category	Variables	Purpose
Core	APP_SECRET_KEY, COLUMN_ENCRYPTION_KEY, DOMAIN	Security and routing
OAuth	GOOGLE_CLIENT_*, GOOGLE_ALLOWED_DOMAIN	Authentication
Database	DATABASE_URL, DB_*	PostgreSQL connection
Rack	RACK_TOKEN, RACK_HOST	Convox connectivity
Email	POSTMARK_*	Email notifications
Audit	AUDIT_HMAC_SECRET, AUDIT_ANCHOR_*	Audit hash chain and S3 anchoring

See Environment Variables for the complete reference.

Deployment Guides

By Platform

Platform	Use Case	Guide
Docker	Development, testing	Docker Deployment
Convox	Production deployments	Convox Deployment
Kubernetes	Custom orchestration	Use Docker image directly

By Security Level

Level	Setup	When to Use
Standard	Public gateway + OAuth	Internal tools, low-risk
Private	Tailscale + OAuth	Sensitive infrastructure
Maximum	Private + MFA + Audit anchoring	Compliance requirements

Infrastructure Components

Required

Component	Purpose	Sizing
PostgreSQL	User data, audit logs	10GB minimum, scale with logs
Gateway container	API server and the web UI (built into the image)	The default convox.yml reserves 128MB RAM and 0.05 CPU

Optional (Recommended)

Component	Purpose	Guide
S3 WORM bucket	Audit anchoring	S3 WORM Storage
KMS key	Encryption at rest	AWS Infrastructure
Tailscale	Private networking	Private Network

Production Readiness

Tip

Before going to production, review the Production Checklist to ensure your deployment meets security requirements.

Key production requirements:

• Strong APP_SECRET_KEY and AUDIT_HMAC_SECRET (256-bit random), and a backed-up COLUMN_ENCRYPTION_KEY
• HTTPS with valid certificates
• Database backups configured
• Anchor bucket’s default Object Lock retention set, and container log retention (LOG_RETENTION_DAYS in convox.yml)
• Admin users configured
• MFA policies enforced
• Monitoring and alerting enabled

Next Steps

• Docker Deployment - Quick start with Docker
• Convox Deployment - Production deployment
• Database Setup - PostgreSQL configuration
• Production Checklist - Go-live preparation