Installation Guide

This guide walks you through setting up PadawanForge for local development and production deployment.

Prerequisites

Required Software

  • Node.js 18+: Modern JavaScript runtime
  • Bun: Fast JavaScript package manager and runtime
  • Git: Version control system
  • Cloudflare Account: For D1 database and Workers deployment
  • VS Code: IDE with TypeScript and Astro extensions
  • Wrangler CLI: Cloudflare Workers development tool (installed with bun)
  • Database Browser: For D1 database inspection

Quick Start

1. Clone Repository

git clone https://github.com/your-org/PadawanForge.git
cd PadawanForge

2. Install Dependencies

bun install

3. Environment Setup

# Create local environment file
touch .dev.vars

# Add required environment variables
echo "API_TOKEN=your_secure_token_here" >> .dev.vars
echo "APP_NAME=PadawanForge" >> .dev.vars
echo "SESSION_DURATION=420" >> .dev.vars
echo "DEFAULT_DIFFICULTY=basic" >> .dev.vars

4. Database Setup

# Create D1 database
bun wrangler d1 create padawan-db

# Update wrangler.jsonc with database ID
# Copy the database_id from the command output

# Run migrations
bun run db:migrate

5. Start Development Server

bun run dev

Visit http://localhost:4321 to see the application running.

Detailed Setup

Environment Configuration

Required Variables (.dev.vars)

# Core application settings
API_TOKEN=your_secure_token_here
APP_NAME=PadawanForge
SESSION_DURATION=420
DEFAULT_DIFFICULTY=basic

# OAuth provider credentials (optional for basic functionality)
OAUTH_GOOGLE_CLIENT_ID=your_google_client_id
OAUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret
OAUTH_DISCORD_CLIENT_ID=your_discord_client_id
OAUTH_DISCORD_CLIENT_SECRET=your_discord_client_secret

OAuth Provider Setup

  1. Google OAuth:

    • Visit Google Cloud Console
    • Create new project or select existing
    • Enable Google+ API
    • Create OAuth 2.0 credentials
    • Add redirect URI: http://localhost:4321/api/auth/callback/google

  2. Discord OAuth:

    • Visit Discord Developer Portal
    • Create new application
    • Go to OAuth2 section
    • Add redirect URI: http://localhost:4321/api/auth/callback/discord

Database Configuration

Wrangler Configuration

Update wrangler.jsonc with your database ID:

{
  "name": "padawanforge",
  "compatibility_date": "2024-09-25",
  "compatibility_flags": ["nodejs_compat"],
  
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "padawan-db",
      "database_id": "your-database-id-here"
    }
  ],
  
  "ai": {
    "binding": "AI"
  },
  
  "kv_namespaces": [
    {
      "binding": "SESSION",
      "id": "your-kv-namespace-id"
    }
  ]
}

KV Namespace Setup

# Create KV namespace for sessions
bun wrangler kv:namespace create "SESSION"

# For preview environment
bun wrangler kv:namespace create "SESSION" --preview

# Update wrangler.jsonc with the namespace IDs

TypeScript Configuration

Generate Cloudflare Types

# Generate types for Cloudflare bindings
bun run cf-typegen

This creates worker-configuration.d.ts with proper TypeScript definitions for your Cloudflare bindings.

Development Commands

Core Development

# Start development server with hot reload
bun run dev

# Build for production
bun run build

# Preview production build locally
bun run preview

Database Operations

# Run migrations locally
bun run db:migrate

# Run migrations on remote database
bun run db:migrate:remote

# Open database console (local)
bun wrangler d1 execute padawan-db --local --command="SELECT * FROM players LIMIT 5;"

# Open database console (remote)
bun wrangler d1 execute padawan-db --command="SELECT COUNT(*) FROM players;"

Testing

# Run comprehensive test suite
bun run test:all

# Test production deployment
bun run test:all:prod

# Test specific components
bun run test:ai
bun run test:demo

Deployment

# Check deployment configuration
bun run check

# Deploy to Cloudflare Workers
bun run deploy

# Run pre-deployment checks
bun run predeploy

Production Deployment

1. Prepare Production Database

# Create production database
bun wrangler d1 create padawan-db-prod

# Update wrangler.jsonc for production
# Run remote migrations
bun run db:migrate:remote

2. Set Production Secrets

# Set API token
bun wrangler secret put API_TOKEN

# Set OAuth credentials
bun wrangler secret put OAUTH_GOOGLE_CLIENT_ID
bun wrangler secret put OAUTH_GOOGLE_CLIENT_SECRET
bun wrangler secret put OAUTH_DISCORD_CLIENT_ID
bun wrangler secret put OAUTH_DISCORD_CLIENT_SECRET

3. Deploy Application

# Deploy with automatic checks
bun run deploy

# Verify deployment
bun run test:all:prod

4. Configure Custom Domain (Optional)

# Add custom domain
bun wrangler custom-domains create your-domain.com

# Update DNS records as instructed
# SSL certificate is automatically provisioned

Verification

Health Checks

# Test local development
curl http://localhost:4321/api/health

# Test production deployment
curl https://your-domain.workers.dev/api/health

# Test AI integration
curl http://localhost:4321/api/ai/test-connection

Database Verification

# Check table creation
bun wrangler d1 execute padawan-db --local --command="SELECT name FROM sqlite_master WHERE type='table';"

# Verify migrations
bun wrangler d1 execute padawan-db --command="SELECT COUNT(*) FROM players;"

Troubleshooting

Common Issues

Database Connection Failed

# Check database configuration
bun wrangler d1 list

# Verify database ID in wrangler.jsonc
grep -A 5 "d1_databases" wrangler.jsonc

# Test database connection
bun wrangler d1 execute padawan-db --command="SELECT 1;"

OAuth Redirect Mismatch

  1. Verify redirect URIs match exactly in provider settings
  2. Check for HTTP vs HTTPS mismatches
  3. Ensure port numbers are correct for development

AI Generation Not Working

# Verify AI binding in wrangler.jsonc
grep -A 3 '"ai"' wrangler.jsonc

# Test AI connection
curl -X POST http://localhost:4321/api/ai/test-connection

Build Failures

# Clear cache and reinstall
rm -rf node_modules bun.lockb
bun install

# Check TypeScript configuration
bun run type-check

# Verify all dependencies
bun run build --verbose

Getting Help

  1. Check the troubleshooting documentation
  2. Review Cloudflare Workers documentation
  3. Check GitHub issues for similar problems
  4. Contact support with detailed error messages

Next Steps

After successful installation:

  1. Read the Quickstart Guide for basic usage
  2. Review the Architecture Overview to understand the system
  3. Explore the API Documentation for integration
  4. Check the Development Guide for testing and debugging

Development Tips

Performance Optimization

  • Use bun instead of npm for faster package management
  • Enable persistent storage for development database
  • Use browser dev tools for frontend debugging
  • Monitor Cloudflare Workers metrics for performance

Code Quality

  • Enable TypeScript strict mode
  • Use ESLint for code consistency
  • Set up pre-commit hooks for automated checks
  • Follow the project’s coding conventions

Security Best Practices

  • Never commit secrets to version control
  • Use environment variables for all configuration
  • Regularly update dependencies
  • Test OAuth flows thoroughly

This installation guide should get you up and running with PadawanForge for both development and production environments. Follow the verification steps to ensure everything is working correctly before proceeding with development.

← Configuration Guide
PadawanForge v1.4.1