Skip to content
Rack Gateway

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

Section titled “Deployment Options”
Docker Run with Docker Compose or standalone containers.
Convox Deploy on Convox racks (recommended for production).
Private Network Deploy behind Tailscale or VPN for maximum security.
Terraform Infrastructure as code for AWS resources.

Architecture Overview

Section titled “Architecture Overview”

Deployment Model

Section titled “Deployment Model”

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

AspectDescription
One gateway per rackEach Convox rack has its own gateway instance
No multi-tenancyGateway manages exactly one rack
Shared databaseGateway uses its own PostgreSQL database
Private networkRecommended: Deploy behind Tailscale/VPN

Prerequisites

Section titled “Prerequisites”

Before deploying, ensure you have:

Required

Section titled “Required”
  • PostgreSQL 14+ - Database for users, tokens, audit logs
  • Google Workspace - OAuth provider for authentication
  • Domain name - For gateway API and web UI
Section titled “Recommended”
  • Tailscale - Private network access
  • Postmark - Email notifications
  • Slack - Real-time notifications
  • S3 bucket - WORM storage for audit anchoring

Quick Start Path

Section titled “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 health endpoints and log in to web UI.

  6. Harden

    Follow the production checklist for security hardening.

Environment Configuration

Section titled “Environment Configuration”

All deployments use the same environment variables. Key categories:

CategoryVariablesPurpose
CoreAPP_SECRET_KEY, DOMAINSecurity and routing
OAuthGOOGLE_CLIENT_*, GOOGLE_ALLOWED_DOMAINAuthentication
DatabaseDATABASE_URL, DB_*PostgreSQL connection
RackRACK_TOKEN, RACK_HOSTConvox connectivity
EmailPOSTMARK_*Email notifications
AuditAUDIT_*, S3 settingsAudit log anchoring

See Environment Variables for the complete reference.

Deployment Guides

Section titled “Deployment Guides”

By Platform

Section titled “By Platform”
PlatformUse CaseGuide
DockerDevelopment, testingDocker Deployment
ConvoxProduction deploymentsConvox Deployment
KubernetesCustom orchestrationUse Docker image directly

By Security Level

Section titled “By Security Level”
LevelSetupWhen to Use
StandardPublic gateway + OAuthInternal tools, low-risk
PrivateTailscale + OAuthSensitive infrastructure
MaximumPrivate + MFA + Audit anchoringCompliance requirements

Infrastructure Components

Section titled “Infrastructure Components”

Required

Section titled “Required”
ComponentPurposeSizing
PostgreSQLUser data, audit logs10GB minimum, scale with logs
Gateway containerAPI server256MB RAM, 0.25 CPU minimum
Web containerStatic SPA64MB RAM, minimal CPU
Section titled “Optional (Recommended)”
ComponentPurposeGuide
S3 WORM bucketAudit anchoringS3 WORM Storage
KMS keyEncryption at restAWS Infrastructure
TailscalePrivate networkingPrivate Network

Production Readiness

Section titled “Production Readiness”

Key production requirements:

  • Strong APP_SECRET_KEY (256-bit random)
  • HTTPS with valid certificates
  • Database backups configured
  • Audit log retention set (LOG_RETENTION_DAYS)
  • Admin users configured
  • MFA policies enforced
  • Monitoring and alerting enabled

Next Steps

Section titled “Next Steps”