Skip to content
Rack Gateway

Quick Start

This guide gets you running locally in about 5 minutes using mock services. You don’t need to configure Google OAuth - the mock OAuth server simulates authentication with test users.

Prerequisites

Section titled “Prerequisites”

Make sure you have these installed:

See System Requirements for detailed installation instructions.

Setup

Section titled “Setup”

  1. Clone the repository

    Terminal window
    git clone https://github.com/DocSpring/rack-gateway.git
    cd rack-gateway

  2. Install tools and dependencies

    Terminal window
    mise install
    task dev-setup   # air, goimports and libfido2 (and Task and Bun if missing)
    go mod download
    cd web && bun install && cd ..

  3. Configuration

    mise.toml already points everything at the mock services, so there’s nothing to configure. Only create a mise.local.toml for your own overrides: don’t copy mise.local.toml.example as it is, because its Google placeholders would replace the mock OAuth settings.

  4. Start everything

    Terminal window
    task dev

    This migrates the database, then starts:

    • Gateway API server at http://localhost:8447
    • Web UI at http://localhost:5223
    • Mock OAuth server at http://localhost:3345
    • Mock Convox API at http://localhost:5443
    • PostgreSQL and MinIO (for audit anchors) in Docker

Try It Out

Section titled “Try It Out”

Web UI

Section titled “Web UI”
  1. Open http://localhost:5223 in your browser
  2. Click Continue with Mock OAuth
  3. The mock OAuth server shows a user selection screen
  4. Choose admin@example.com, the one user the dev stack creates (see Test Users for the others)
  5. MFA is required for every user by default, so you land on Account Security: enroll an authenticator app (any TOTP app works), and then the other pages open

CLI

Section titled “CLI”

  1. Build the CLI and log in

    Terminal window
    task go:build:cli
    ./bin/rack-gateway login staging http://localhost:8447

    Your browser opens to the mock OAuth server. Select a test user.

  2. Run Convox commands

    Terminal window
    # List apps (from mock Convox)
    ./bin/rack-gateway apps
    

    # View processes
    ./bin/rack-gateway ps
    

    # Check rack status
    ./bin/rack-gateway rack

  3. Set up a convenient alias

    Terminal window
    alias cg="./bin/rack-gateway"
    cg apps
    cg ps

What You’re Running

Section titled “What You’re Running”

The development environment consists of:

ComponentURLDescription
Gateway APIhttp://localhost:8447Authentication proxy
Web UIhttp://localhost:5223Admin interface (Vite dev server)
Mock OAuthhttp://localhost:3345Simulates Google OAuth
Mock Convoxhttp://localhost:5443Simulates Convox rack API
PostgreSQLlocalhost:55432Database (in Docker)

Test Users

Section titled “Test Users”

The mock OAuth server offers four test users:

EmailRoleCapabilities
admin@example.comAdminFull access to everything
deployer@example.comDeployerDeploy apps, manage builds and releases
ops@example.comOpsRestart apps, manage processes
viewer@example.comViewerRead-only access

The gateway only lets in users it knows, and the dev stack creates just admin@example.com (ADMIN_USERS in mise.toml). To try the others, add them on the Users page as the admin, or seed them in your mise.local.toml:

[env]
DEPLOYER_USERS = "deployer@example.com"
OPERATIONS_USERS = "ops@example.com"
VIEWER_USERS = "viewer@example.com"

Explore the Features

Section titled “Explore the Features”

User Management

Section titled “User Management”
  1. Login as admin@example.com
  2. Go to Users in the sidebar
  3. Add deployer@example.com with the Deployer role
  4. Try changing a user’s roles

API Tokens

Section titled “API Tokens”
  1. Go to API Tokens
  2. Create a new token with the CI/CD role shortcut
  3. Note a token can’t have permissions its owner’s role lacks

Audit Logs

Section titled “Audit Logs”
  1. Go to Audit Logs
  2. See all actions you’ve taken, each recorded before it ran
  3. Note that env values are redacted

Account Security

Section titled “Account Security”
  1. Go to Account Security
  2. Add a second MFA method, or regenerate your backup codes
  3. Click your name at the bottom of the sidebar to see your active sessions

Run Tests

Section titled “Run Tests”

Verify everything is working:

Terminal window
# Go unit tests
task go:test:unit


# Web unit tests
task web:test


# Lint and fix
task lint:fix

Next Steps

Section titled “Next Steps”

Now that you have Rack Gateway running locally:

Troubleshooting

Section titled “Troubleshooting”

Port already in use

Section titled “Port already in use”

If you see port conflict errors:

Terminal window
# Stop all services
task docker:down


# Restart
task dev

Database connection failed

Section titled “Database connection failed”

Ensure Docker is running:

Terminal window
docker ps  # Should show rack-gateway-postgres-1

If the container isn’t running:

Terminal window
task docker:reset
task dev

OAuth redirect issues

Section titled “OAuth redirect issues”

Make sure you’re using the mock OAuth server URLs:

  • Gateway: http://localhost:8447 (not https)
  • OAuth redirect: http://localhost:8447/api/v1/auth/web/callback
  • No mise.local.toml overriding GOOGLE_OAUTH_BASE_URL or GOOGLE_ALLOWED_DOMAIN

For more help, see Troubleshooting.