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.

Tip

This quick start is perfect for evaluation and local development. For production deployment, see the Deployment Guide.

Prerequisites

Make sure you have these installed:

• Go 1.22+ - Install Go
• Docker & Docker Compose - Install Docker
• Bun 1.3+ - Install Bun
• mise - Install mise

See System Requirements for detailed installation instructions.

Setup

1. Clone the repository

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

2. Install dependencies

   go mod download
   cd web && bun install && cd ..

3. Configure environment

   The default configuration uses mock services. Just copy the example file:

   cp mise.local.toml.example mise.local.toml

4. Start everything

   task dev

   This 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 database in Docker

Try It Out

Web UI

1. Open http://localhost:5223 in your browser

2. Click “Sign in with Google”

3. The mock OAuth server shows a user selection screen

4. Choose a test user:

   • admin@example.com - Full access
   • deployer@example.com - Deployment permissions
   • ops@example.com - Operations permissions
   • viewer@example.com - Read-only access

5. You’ll be redirected to the dashboard

CLI

1. Login to the gateway

   ./bin/rack-gateway login staging http://localhost:8447

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

2. Run Convox commands

   # 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

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

What You’re Running

The development environment consists of:

Component	URL	Description
Gateway API	http://localhost:8447	Authentication proxy
Web UI	http://localhost:5223	Admin interface (Vite dev server)
Mock OAuth	http://localhost:3345	Simulates Google OAuth
Mock Convox	http://localhost:5443	Simulates Convox rack API
PostgreSQL	localhost:55432	Database (in Docker)

Test Users

The mock OAuth server provides four test users with different roles:

Email	Role	Capabilities
admin@example.com	Admin	Full access to everything
deployer@example.com	Deployer	Deploy apps, manage builds and releases
ops@example.com	Ops	Restart apps, manage processes
viewer@example.com	Viewer	Read-only access

Explore the Features

User Management

1. Login as admin@example.com
2. Go to Users in the sidebar
3. View all users and their roles
4. Try changing a user’s role

API Tokens

1. Go to API Tokens
2. Create a new token for CI/CD
3. Note the token permissions match the user’s role

Audit Logs

1. Go to Audit Logs
2. See all actions you’ve taken
3. Note that secrets are automatically redacted

Account Security

1. Go to Account Security
2. Try enrolling a TOTP authenticator
3. View your active sessions

Run Tests

Verify everything is working:

# Run all tests
task test

# Run linters
task lint

Next Steps

Now that you have Rack Gateway running locally:

Evaluate

• Explore the RBAC system
• Try the MFA features
• Review the audit logs

Deploy

• Set up Google OAuth
• Review Production Checklist
• Deploy with Docker or Convox

Develop

• Read the Development Guide
• Understand the Architecture
• Check the Contributing Guide

Troubleshooting

Port already in use

If you see port conflict errors:

# Stop all services
task docker:down

# Restart
task dev

Database connection failed

Ensure Docker is running:

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

If the container isn’t running:

task docker:reset
task dev

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/callback

For more help, see Troubleshooting.