Local Development Guide

This guide explains how to set up and run GitHub.gg locally for development without requiring all external API keys.

Overview

GitHub.gg is designed to work in different modes:

Full Mode: All features enabled with complete API keys
Development Mode: Core features with graceful degradation for missing APIs
Demo Mode: Mock data for demonstration purposes

Quick Start

1. Automated Setup (Recommended)

# Clone the repository
git clone https://github.com/lantos1618/github.gg.git
cd github.gg

# Run the automated setup
bun run setup

This will:

Install dependencies
Create .env.local with development defaults
Start PostgreSQL database
Run database migrations

2. Authentication Setup

The app uses a unified authentication system powered by better-auth:

Core Authentication (Required for Production)

Primary System: GitHub OAuth via better-auth
Single Source of Truth: One session, one user identity
Enhanced Features: Optional GitHub App installation for private repos

To set up GitHub OAuth:

Go to GitHub Developer Settings
Click "New OAuth App"
Configure:
- Application name: github.gg-dev
- Homepage URL: http://localhost:3000
- Authorization callback URL: http://localhost:3000/api/auth/callback/github
Copy the Client ID and Client Secret

Update .env.local:

GITHUB_CLIENT_ID="your-client-id"
GITHUB_CLIENT_SECRET="your-client-secret"

Development Mode (Optional)

Set NEXT_PUBLIC_USE_DEV_AUTH=true for simplified local testing
Uses JWT-based authentication without GitHub OAuth
Pre-configured development users
Note: Only for development, not production

3. Start Development Server

bun dev

Visit http://localhost:3000

Environment Variables

Required Variables

These are absolutely required for the app to start:

Variable	Description	Development Default
`DATABASE_URL`	PostgreSQL connection	Auto-configured by Docker
`BETTER_AUTH_SECRET`	Session encryption	Auto-generated
`GITHUB_CLIENT_ID`	GitHub OAuth Client ID	Must be set manually
`GITHUB_CLIENT_SECRET`	GitHub OAuth Client Secret	Must be set manually
`NEXT_PUBLIC_APP_URL`	App URL	`http://localhost:3000`

Optional Variables

These enable additional features but the app works without them:

Variable	Description	Feature
`GITHUB_PUBLIC_API_KEY`	GitHub Personal Access Token	Enhanced repository analysis
`GEMINI_API_KEY`	Google Gemini API Key	AI-powered insights
`STRIPE_*`	Stripe payment keys	Payment features
`POSTHOG_*`	PostHog analytics keys	Analytics

Development Mode Features

When NODE_ENV=development (default in local setup):

Graceful Degradation

Missing GitHub API Key: Uses basic repository data, shows upgrade prompts
Missing AI API Key: Disables AI features, shows "coming soon" messages
Missing Payment Keys: Shows mock payment UI, no actual transactions
Missing Analytics: Logs events to console in development, no data collection

Mock GitHub Repositories

In development mode, the app provides mock repository data for testing:

dev/dev-project: Sample development project with JavaScript, Express server

This repository works exactly like a real GitHub repository:

Full file browsing and content viewing
Repository statistics and metadata
Branch information
Language breakdowns
All features work without external API calls

Mock File Structure: The mock data is stored in /repo/dev/dev-project/ directory to avoid exposing the actual project structure.

Visit /dev page to see the available mock repository and test the full application.

Development Enhancements

Enhanced error messages and debugging
Development-only UI elements
Mock data for testing
Hot reload improvements

Database Management

Local Database

The setup script automatically configures a PostgreSQL database using Docker:

# Start database
bun run db:start

# Stop database
bun run db:stop

# Reset database (⚠️ Destructive)
bun run db:reset

# View in Drizzle Studio
bun run db:studio

Database Schema

The database includes tables for:

User accounts and sessions
GitHub installations
Repository analysis data
Payment subscriptions
API key storage

Testing

Running Tests

# All tests
bun test

# Specific test categories
bun run test:payment
bun run test:all

Test Environment

Tests use:

Separate test database
Mock external APIs
Isolated environment variables
No external dependencies

Development Workflow

1. Local Development

# Start development
bun dev

# Make changes to code
# Hot reload will automatically apply changes

2. Testing Changes

# Run tests
bun test

# Check code quality
bun run lint

3. Database Changes

# Generate migration
bun run db:generate

# Apply migration
bun run db:push

4. Preview Deployment

# Push to feature branch
git push origin feature/your-feature

# Create PR on GitHub
# Vercel will automatically deploy preview

Troubleshooting

Common Issues

Database Connection Failed:

# Restart database
bun run db:stop
bun run db:start

Port 3000 Already in Use:

# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>

Environment Variables Missing:

# Recreate .env.local
rm .env.local
bun run setup

Docker Issues:

# Restart Docker
docker system prune -a
docker-compose down
docker-compose up -d postgres

Development Tips

Use Development Mode: Always run with NODE_ENV=development
Check Logs: Monitor console for error messages
Database Studio: Use bun run db:studio to inspect data
Hot Reload: Changes to most files will auto-reload
Environment: Keep .env.local updated with your keys

Optional Features Setup

GitHub API Enhancement

For better repository analysis:

Create GitHub Personal Access Token
Add to .env.local:
```
GITHUB_PUBLIC_API_KEY="your-token"
```

AI Analysis Features

For AI-powered insights:

Get Gemini API key from Google AI Studio
Add to .env.local:
```
GEMINI_API_KEY="your-key"
```

Payment Features

For payment integration:

Set up Stripe account
Get test keys from Stripe Dashboard

Add to .env.local:

STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
STRIPE_BYOK_PRICE_ID="price_..."
STRIPE_PRO_PRICE_ID="price_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."

Analytics Features

For PostHog analytics:

Set up PostHog account
Get API keys from PostHog Dashboard