Codakey
Play
← Back to frontier

How to Deploy & Use frontier

Frontier Deployment & Usage Guide

1. Prerequisites

Before deploying Frontier, ensure you have the following installed:

Runtime & Tools:

  • Go 1.21+ (required for building from source)
  • PostgreSQL 13+ (primary database)
  • Docker (optional, for containerized deployment)
  • Git (for cloning the repository)

External Services (Optional but recommended for production):

  • Stripe account (for billing features - see billing/subscription/service.go and billing/checkout/service.go)
  • Email service (for OTP authentication)
  • Social login providers (Google, GitHub, etc. for social authentication)

Accounts to configure:

  • Database credentials with appropriate privileges
  • Stripe API keys (if using billing features)
  • OAuth client IDs/secrets for social providers

2. Installation

Binary Installation (Recommended)

Download the latest binary for your platform:

# Cross-platform (download from releases)
# Visit: https://github.com/raystack/frontier/releases

# macOS (Homebrew)
brew install raystack/tap/frontier

# Linux (DEB/RPM packages)
# Download .deb or .rpm from releases and install:
sudo dpkg -i frontier_*.deb  # Debian/Ubuntu
sudo rpm -i frontier_*.rpm   # RHEL/CentOS/Fedora

# Windows (Scoop)
scoop bucket add frontier https://github.com/raystack/scoop-bucket.git
scoop install frontier

Docker Installation

# Pull the latest image
docker pull raystack/frontier:latest

# Or a specific version
docker pull raystack/frontier:0.11.3

From Source

# Clone the repository
git clone https://github.com/raystack/frontier.git
cd frontier

# Build the binary
go build -o frontier ./cmd/frontier

# Verify installation
./frontier --help

3. Configuration

Frontier can be configured via environment variables or a configuration file. Key configuration options:

Essential Environment Variables

# Database Configuration
FRONTIER_DB_HOST=localhost
FRONTIER_DB_PORT=5432
FRONTIER_DB_USER=frontier
FRONTIER_DB_PASSWORD=your_password
FRONTIER_DB_NAME=frontier
FRONTIER_DB_SSLMODE=disable  # Use "require" for production

# Server Configuration
FRONTIER_HTTP_HOST=0.0.0.0
FRONTIER_HTTP_PORT=8080
FRONTIER_GRPC_HOST=0.0.0.0
FRONTIER_GRPC_PORT=8081

# Authentication Configuration
FRONTIER_AUTH_EMAIL_OTP_EXPIRY=10m  # OTP expiry duration
FRONTIER_AUTH_JWT_SECRET=your_jwt_secret_key_here
FRONTIER_AUTH_JWT_RS256_PRIVATE_KEY_PATH=/path/to/private.key
FRONTIER_AUTH_JWT_RS256_PUBLIC_KEY_PATH=/path/to/public.key

# Billing Configuration (Stripe)
FRONTIER_BILLING_STRIPE_SECRET_KEY=sk_test_...
FRONTIER_BILLING_STRIPE_WEBHOOK_SECRET=whsec_...
FRONTIER_BILLING_DEFAULT_CURRENCY=usd

# Email Configuration (for OTP)
FRONTIER_SMTP_HOST=smtp.gmail.com
FRONTIER_SMTP_PORT=587
FRONTIER_SMTP_USERNAME=your_email@gmail.com
FRONTIER_SMTP_PASSWORD=your_app_password
FRONTIER_SMTP_FROM_EMAIL=noreply@yourdomain.com

Social Login Configuration

# Google OAuth
FRONTIER_AUTH_GOOGLE_CLIENT_ID=your_google_client_id
FRONTIER_AUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret

# GitHub OAuth
FRONTIER_AUTH_GITHUB_CLIENT_ID=your_github_client_id
FRONTIER_AUTH_GITHUB_CLIENT_SECRET=your_github_client_secret

# Add other providers as needed

Configuration File

Create a config.yaml file:

app:
  name: frontier
  host: "0.0.0.0"
  port: 8080
  grpc_port: 8081

log:
  level: "info"
  format: "json"

db:
  host: "localhost"
  port: 5432
  name: "frontier"
  user: "frontier"
  password: "your_password"
  sslmode: "disable"

auth:
  jwt:
    secret: "your_jwt_secret_key_here"
    rs256:
      private_key_path: "/path/to/private.key"
      public_key_path: "/path/to/public.key"
  email_otp_expiry: "10m"

billing:
  stripe:
    secret_key: "sk_test_..."
    webhook_secret: "whsec_..."
  default_currency: "usd"

4. Build & Run

Development Mode

# Clone and navigate to project
git clone https://github.com/raystack/frontier.git
cd frontier

# Install dependencies
go mod download

# Set up environment variables
export FRONTIER_DB_HOST=localhost
export FRONTIER_DB_PORT=5432
export FRONTIER_DB_USER=frontier
export FRONTIER_DB_PASSWORD=your_password
export FRONTIER_DB_NAME=frontier

# Run database migrations
go run cmd/frontier/main.go migrate up

# Start the server in development mode
go run cmd/frontier/main.go serve

Production Build

# Build optimized binary
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o frontier ./cmd/frontier

# Run migrations
./frontier migrate up

# Start server
./frontier serve

Docker Compose (Development)

Create a docker-compose.yml file:

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: frontier
      POSTGRES_USER: frontier
      POSTGRES_PASSWORD: frontier123
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  frontier:
    image: raystack/frontier:latest
    depends_on:
      - postgres
    environment:
      FRONTIER_DB_HOST: postgres
      FRONTIER_DB_PORT: 5432
      FRONTIER_DB_USER: frontier
      FRONTIER_DB_PASSWORD: frontier123
      FRONTIER_DB_NAME: frontier
      FRONTIER_DB_SSLMODE: disable
      FRONTIER_HTTP_HOST: 0.0.0.0
      FRONTIER_HTTP_PORT: 8080
    ports:
      - "8080:8080"
      - "8081:8081"
    command: ["serve"]

volumes:
  postgres_data:

Run with:

docker-compose up -d

5. Deployment

Platform Recommendations

Kubernetes (Production)

# Example Kubernetes deployment manifest
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontier
spec:
  replicas: 3
  selector:
    matchLabels:
      app: frontier
  template:
    metadata:
      labels:
        app: frontier
    spec:
      containers:
      - name: frontier
        image: raystack/frontier:latest
        ports:
        - containerPort: 8080
          name: http
        - containerPort: 8081
          name: grpc
        env:
        - name: FRONTIER_DB_HOST
          valueFrom:
            secretKeyRef:
              name: frontier-secrets
              key: db-host
        # Add other environment variables from secrets/configmap

Docker Swarm

# Create a Docker stack
docker stack deploy -c docker-compose.prod.yml frontier

Traditional VPS (DigitalOcean, AWS EC2, etc.)

  1. Set up PostgreSQL database
  2. Install Frontier binary
  3. Configure systemd service:
# /etc/systemd/system/frontier.service
[Unit]
Description=Frontier IAM Service
After=network.target postgresql.service

[Service]
Type=simple
User=frontier
WorkingDirectory=/opt/frontier
EnvironmentFile=/etc/frontier/frontier.conf
ExecStart=/usr/local/bin/frontier serve
Restart=on-failure

[Install]
WantedBy=multi-user.target

Platform as a Service

  • Fly.io: Good for containerized Go applications
  • Railway.app: Easy PostgreSQL integration
  • Render.com: Simple deployment with managed databases

Database Setup

-- Create database and user
CREATE DATABASE frontier;
CREATE USER frontier WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE frontier TO frontier;

-- For production, consider:
ALTER DATABASE frontier SET timezone TO 'UTC';

Reverse Proxy Setup (Nginx)

# /etc/nginx/sites-available/frontier
server {
    listen 80;
    server_name frontier.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # For GRPC if needed
    location /grpc {
        grpc_pass grpc://localhost:8081;
    }
}

6. Troubleshooting

Common Issues

1. Database Connection Errors

# Error: "failed to connect to database"
# Solution: Verify database is running and credentials are correct
psql -h localhost -U frontier -d frontier -c "SELECT 1;"

# Check environment variables
echo $FRONTIER_DB_HOST
echo $FRONTIER_DB_PORT

2. Migration Failures

# Run migrations manually
./frontier migrate status
./frontier migrate up --step 1  # Apply one migration at a time

# Reset development database (caution: destroys data)
./frontier migrate reset

3. Authentication Issues

  • JWT errors: Ensure FRONTIER_AUTH_JWT_SECRET is set and consistent across instances
  • Social login failures: Verify OAuth client IDs and secrets are correctly configured
  • OTP not sending: Check SMTP configuration and email service status

4. Billing/Stripe Integration Problems

# Check Stripe webhook configuration
# Ensure FRONTIER_BILLING_STRIPE_WEBHOOK_SECRET is set
# Verify webhook endpoint is reachable from Stripe

# Test Stripe connection
curl https://api.stripe.com/v1/balance \
  -u sk_test_...:

5. Service User Creation Issues

  • Refer to internal/api/v1beta1connect/user.go for user creation logic
  • Check if organization/group IDs exist when filtering users
  • Verify user state transitions are valid

6. High Memory/CPU Usage

  • Check for connection leaks in database
  • Review cron job configurations in billing services
  • Monitor with: ./frontier metrics (if metrics are enabled)

7. Logging and Debugging

# Increase log level for debugging
export FRONTIER_LOG_LEVEL=debug
./frontier serve

# Check structured logs for specific errors
journalctl -u frontier.service -f --output=json

8. Port Already in Use

# Check what's using the port
sudo lsof -i :8080
sudo lsof -i :8081

# Kill the process or change Frontier ports
export FRONTIER_HTTP_PORT=8082
export FRONTIER_GRPC_PORT=8083

Getting Help

← Project overviewView alternatives to frontier →