Skip to main content

​
Overview

Openlane UI offers two primary installation paths:

Console Application

Full SaaS platform for compliance management (requires backend API)

Component Library

Install @repo/ui package for use in your own projects

​
Console Application Installation

​
System Requirements

Ensure your system meets these requirements before proceeding.
RequirementVersionNotes
Bun1.2.16+JavaScript runtime and package manager
Node.js24.14.xRequired by some dependencies
GitLatestFor version control
TaskLatestOptional but recommended for running commands
Operating SystemmacOS, Linux, WindowsSee platform-specific notes below

​
Platform-Specific Setup

Recommended: Use the automated setup script
# Clone repository
git clone [email protected]:theopenlane/openlane-ui.git
cd openlane-ui

# Run automated setup
task local-setup
This installs:
  • Bun package manager via curl
  • Pre-commit hooks via Homebrew
  • All project dependencies
  • Git hooks for code quality

​
Environment Configuration

1

Copy Environment Template

cp ./config/.env.example ./apps/console/.env
Turbo v2 requires .env files in the app directory (apps/console/.env), not the monorepo root.
2

Configure Core Settings

Edit apps/console/.env with your configuration:
# Site Configuration
NEXT_PUBLIC_SITE_URL=http://localhost:3001

# Backend API URLs (adjust port if needed)
NEXT_PUBLIC_OPENLANE_URL=http://localhost:17608
NEXT_PUBLIC_API_GQL_URL=http://localhost:17608/query
API_REST_URL=http://localhost:17608
API_GQL_URL=http://localhost:17608/query

# Authentication Secrets (generate new ones)
AUTH_SECRET=$(openssl rand -base64 32)
NEXTAUTH_SECRET=$(openssl rand -base64 32)

# Session Configuration
SESSION_COOKIE_NAME=temporary-cookie
SESSION_COOKIE_DOMAIN=              # Leave empty for localhost
SESSION_COOKIE_EXPIRATION_MINUTES=10
SESSION_NEXAUTH_MAX_AGE=7200
COOKIE_DOMAIN=                      # Leave empty for localhost

# Domain Restrictions
NEXT_PUBLIC_ALLOWED_LOGIN_DOMAINS=  # Leave empty to allow all domains
3

Configure OAuth Providers (Optional)

  1. Go to GitHub Developer Settings
  2. Create a new OAuth App or GitHub App
  3. Set authorization callback URL: http://localhost:3001/api/auth/callback/github
  4. Add credentials to .env:
AUTH_GITHUB_ID=your_client_id
AUTH_GITHUB_SECRET=your_client_secret
GitHub OAuth Documentation →
4

Configure Optional Features

# Enable billing features
NEXT_PUBLIC_ENABLE_PLAN=true
STRIPE_SECRET_KEY=sk_test_...

NEXT_PUBLIC_AI_SUGGESTIONS_ENABLED=true
GOOGLE_AI_PROJECT_ID=your-project-id
GOOGLE_AI_REGION=us-central1
GOOGLE_AI_MODEL_NAME=gemini-2.5-flash
GEMINI_API_KEY=your-api-key
GOOGLE_APPLICATION_CREDENTIALS=.env.service-account-key.json
GOOGLE_RAG_CORPUS_ID=your-corpus-id

NEXT_PUBLIC_INCLUDE_QUESTIONNAIRE_CREATION=true
NEXT_PUBLIC_SURVEYJS_KEY=your-license-key  # Optional for local dev

NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your-maps-api-key

NEXT_PUBLIC_PIRSCH_KEY=your-public-key
PIRSCH_SECRET=your-secret-key
PIRSCH_CLIENT_ID=your-client-id

# Enable chatbot
NEXT_PUBLIC_ENABLE_CHATBOT=true

# DevRev Support Chat
NEXT_PUBLIC_ENABLE_DEVREV_CHAT=true
NEXT_PUBLIC_CHAT_APP_ID=your-app-id
DEVREV_AAT=your-auth-token

NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your-site-key
RECAPTCHA_SECRET_KEY=your-secret-key

​
Backend API Setup

The console requires the Openlane backend API. It cannot function standalone.
1

Clone Core Repository

git clone [email protected]:theopenlane/core.git
cd core
2

Follow Backend Setup

Refer to the core repository documentation for:
  • Database setup
  • API configuration
  • Test data creation
  • Running the server
3

Verify Backend

Ensure the API is running:
# Test REST endpoint
curl http://localhost:17608/livez

# Test GraphQL endpoint
curl http://localhost:17608/query -X POST \
  -H "Content-Type: application/json" \
  -d '{"query":"{__schema{types{name}}}"}'

​
Development Workflow

1

Install Dependencies

task install
# or
bun install
2

Start Development Server

task dev:console
# or
bun dev --filter={apps/console}
Opens on http://localhost:3001
3

Build for Production

task build
# or
bun run build
Outputs:
  • Console: .next/ directory
  • Storybook: storybook-static/ directory

​
Component Library Installation

Use the @repo/ui package in your own projects.
The component library is currently workspace-only. For external use, you’ll need to clone the repository.

​
Using in the Monorepo

If you’re adding a new app to the Openlane UI monorepo:
1

Add Package Dependency

In your app’s package.json:
{
  "dependencies": {
    "@repo/ui": "workspace:*"
  }
}
2

Install Peer Dependencies

{
  "dependencies": {
    "react": "19.2.4",
    "react-dom": "19.2.4",
    "next": "16.1.6",
    "tailwindcss": "^4.1.13"
  }
}
3

Import Styles

In your root layout or app entry:
import '@repo/ui/styles.css'
4

Configure Tailwind

Create tailwind.config.ts:
import type { Config } from 'tailwindcss'
import sharedConfig from '@repo/tailwind-config'

const config: Config = {
  ...sharedConfig,
  content: [
    './src/**/*.{ts,tsx}',
    '../../packages/ui/src/**/*.{ts,tsx}',
  ],
}

export default config
5

Use Components

Import and use any component:
import { Button } from '@repo/ui/button'
import { Input } from '@repo/ui/input'
import { Card } from '@repo/ui/cardpanel'

export default function MyPage() {
  return (
    <Card>
      <Input placeholder="Enter text..." />
      <Button>Submit</Button>
    </Card>
  )
}

​
Available Components

The @repo/ui package includes 50+ components:
  • button - Customizable button with variants
  • input - Text input field
  • textarea - Multi-line text input
  • select - Dropdown select
  • checkbox - Checkbox input
  • switch - Toggle switch
  • radio-group - Radio button group
  • form - Form wrapper with validation
  • label - Form label
  • password-input - Password field with toggle
  • input-otp - One-time password input
  • tag-input - Multi-tag input
  • calendar - Date picker
  • calendar-popover - Calendar in popover
  • cardpanel - Card container
  • panel - Generic panel
  • grid - Grid layout
  • separator - Divider line
  • tabs - Tab navigation
  • sheet - Slide-out panel
  • table - Basic table
  • data-table - Advanced data table with sorting/filtering
  • badge - Status badge
  • avatar - User avatar
  • line-chart - Line chart visualization
  • donut-chart - Donut chart
  • tag - Label tag
  • progress-circle - Circular progress indicator
  • alert - Alert message
  • alert-dialog - Modal alert dialog
  • dialog - Generic dialog
  • confirmation-dialog - Confirm action dialog
  • toast / toaster - Toast notifications
  • popover - Popover overlay
  • tooltip - Tooltip
  • page-heading - Page header
  • logo - Openlane logo
  • kbd - Keyboard shortcut display
  • info - Info tooltip
  • message-box - Message container
  • country-dropdown - Country selector
  • country-flag - Flag icon
  • infinite-scroll - Infinite scroll container
  • multiple-selector - Multi-select input
View all components in Storybook.

​
Verification & Testing

​
Verify Installation

# Check if console is accessible
curl http://localhost:3001

# Verify build works
task build

# Run linter
task lint

​
Common Build Commands

CommandDescription
task installInstall all dependencies
task buildBuild all apps and packages
task devStart all apps in dev mode
task dev:consoleStart console app only
task dev:storybookStart Storybook only
task cleanRemove build artifacts and node_modules
task reinstallClean and reinstall everything
task lintRun ESLint
task precommit-fullRun all pre-commit hooks

​
Troubleshooting

Symptoms: curl command fails or Bun doesn’t installSolutions:
  1. Check internet connection
  2. Verify system compatibility (Bun requires Linux/macOS/WSL2)
  3. Try manual download from bun.sh
  4. On Windows, use WSL2 instead of native Windows
Symptoms: bun install fails with resolution errorsSolutions:
# Clear cache and reinstall
rm -rf node_modules bun.lock
bun install

# Or use task command
task reinstall
Symptoms: Build fails with type errorsSolutions:
# Rebuild packages
bun run turbo-clean
task build

# Check TypeScript version
bun --version
Symptoms: App can’t connect to backend or features missingSolutions:
  1. Verify .env is in apps/console/ not root
  2. Restart dev server after .env changes
  3. Check for typos in variable names
  4. Use NEXT_PUBLIC_ prefix for client-side variables
Symptoms: “Port already in use” errorSolutions:
# Find process using port
lsof -i :3001
# or
netstat -an | grep 3001

# Kill process or change port in package.json
"dev": "next dev -p 3002"
Symptoms: Codegen errors or missing typesSolutions:
# Regenerate GraphQL code
cd packages/codegen
task codegen:codegen

# Ensure backend schema is accessible
curl http://localhost:17608/query
Symptoms: Components render but have no stylesSolutions:
  1. Verify @repo/ui/styles.css is imported
  2. Check Tailwind config includes UI package path
  3. Restart dev server
  4. Clear .next cache: rm -rf .next

​
Next Steps

Console Features

Explore the console application capabilities

Component Usage

Learn how to use the component library

Architecture

Understand the monorepo structure

Development Guide

Deep dive into development workflows

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us