System Requirements

This page covers the requirements for both local development and production deployment.

Development Requirements

Required Software

Software	Version	Purpose
mise	Latest	Tool versions and environment variables (mise install installs the pinned Go, Bun, Node and golangci-lint)
Go	1.26.10+ (mise.toml pins 1.27.3)	Gateway server and CLI
Bun	1.4+ (mise.toml pins 1.4.3)	Web frontend build tool
Docker	20.10+	PostgreSQL, MinIO and the E2E stack
Docker Compose	2.0+	Container orchestration
Task	3.x	Task runner: every build, test and lint command is a task
Overmind	Latest	Runs the local services for task dev

Optional Software

Software	Purpose
libfido2	WebAuthn/FIDO2 support in the CLI (the CLI build needs it unless you build with -tags nofido)

Installation

macOS

# Install Homebrew if not present
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required software
brew install mise
mise install          # Go, Bun, Node and golangci-lint at the pinned versions
brew install --cask docker
brew install go-task/tap/go-task overmind

# Install optional software
brew install libfido2

Linux (Ubuntu/Debian)

# mise, then the pinned Go, Bun, Node and golangci-lint
curl https://mise.jdx.dev/install.sh | sh
mise install

# Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# Task runner
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin

# Overmind (needs tmux): see https://github.com/DarthSim/overmind#installation

# libfido2 (for WebAuthn CLI support)
sudo apt-add-repository ppa:yubico/stable
sudo apt-get update
sudo apt-get install libfido2-dev

Automated

If you have the Task runner installed:

# Install air, goimports and libfido2 (and Task and Bun if missing)
task dev-setup

Or install Task first:

# macOS
brew install go-task/tap/go-task && task dev-setup

# Linux
curl -sL https://taskfile.dev/install.sh | sh -s -- -b /usr/local/bin && task dev-setup

Production Requirements

Gateway Server

Component	Requirement
CPU	The default convox.yml reserves 0.05 vCPU
Memory	The default convox.yml reserves 128 MB (also its memory limit)
OS	Linux (x86_64): the published image is linux/amd64

The gateway is lightweight; the admin service that runs migrations reserves 0.25 vCPU and 512 MB while it runs.

Database

Component	Requirement
PostgreSQL	16 (what the dev and test stacks run)
Storage	1GB+ (grows with audit logs, which are never deleted)
Connections	Up to 20 per gateway process (two pools of DB_MAX_OPEN_CONNS, default 10)

Managed PostgreSQL Recommended

For production, use a managed PostgreSQL service (RDS, Cloud SQL, etc.) for automatic backups and high availability.

Network

Port	Service	Access
8080 (default PORT)	Gateway API (plain HTTP behind your TLS terminator)	Internal or VPN
443	HTTPS (via load balancer or ingress)	Users/CI/CD
5432	PostgreSQL	Gateway only
5443	Convox rack API (outbound from the gateway)	Gateway only

Environment Configuration

Rack Gateway uses mise for environment variable management. Configuration is stored in:

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

Required Environment Variables

For development, the defaults in mise.toml work with mock services. In production the gateway reads its configuration from the environment of its container (for example convox env set or Terraform), not from mise. The minimum is:

# OAuth
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_ALLOWED_DOMAIN=your-company.com
DOMAIN=gateway.your-company.com

# Database
DATABASE_URL=postgres://user:pass@host:5432/rack_gateway?sslmode=require

# Secrets (each at least 32 random bytes; generate them, never reuse the dev values)
APP_SECRET_KEY=...
AUDIT_HMAC_SECRET=...
COLUMN_ENCRYPTION_KEY=...   # base64 of exactly 32 bytes

# Convox Rack
RACK_HOST=https://api.rack.convox.cloud
RACK_TOKEN=your-rack-token
RACK_ALIAS=production
ADMIN_USERS=you@your-company.com

Add AUDIT_ANCHOR_BUCKET and AUDIT_ANCHOR_CHAIN_ID for WORM anchors. See the Production Checklist.

See Configuration Reference for all options.

Convox Rack Requirements

To use Rack Gateway, you need:

1. Self-hosted Convox rack - The rack API endpoint
2. Rack API token - Found in Terraform state or Convox Console
3. Network access - Gateway must reach the rack API

Supported Convox Versions

• Convox v3 (Kubernetes-based) - Fully supported
• Convox v2 (ECS-based) - Not tested, may work

Google Workspace Requirements

For OAuth authentication:

1. Google Cloud Project with OAuth 2.0 credentials
2. Google Workspace domain for user restriction
3. Authorized redirect URI configured in GCP Console

See OAuth Setup for detailed instructions.

Hardware Security Keys (Optional)

For WebAuthn/FIDO2 MFA support:

Supported Devices

• YubiKey 5 series (USB-A, USB-C, NFC)
• YubiKey Security Key series
• Platform authenticators (Touch ID, Windows Hello), in the web UI only
• Any FIDO2-compatible authenticator

CLI Requirements

The rack-gateway CLI requires libfido2 for WebAuthn support:

macOS

brew install libfido2

Linux

# Ubuntu/Debian
sudo apt-add-repository ppa:yubico/stable
sudo apt-get update
sudo apt-get install libfido2-dev

# Fedora
sudo dnf install libfido2-devel

Note

A CLI built without libfido2 (-tags nofido, like the prebuilt Linux release) can still authenticate but won’t support WebAuthn MFA. TOTP, YubiKey OTP and backup codes work without libfido2.

Verifying Installation

After installing dependencies:

# Check Go version
go version  # Should show 1.26.10 or newer

# Check Docker
docker --version
docker compose version

# Check Bun
bun --version  # Should show 1.4+

# Check mise
mise --version

# Optional: Check libfido2
pkg-config --modversion libfido2  # macOS/Linux

Then follow the Quick Start to verify everything works.

Next Steps

• Quick Start - Get running locally
• OAuth Setup - Configure Google OAuth for production
• Deployment Guide - Production deployment options