Installation

Installation Guide

This comprehensive guide covers everything you need to install and configure Solo Kit for development.

📋 Prerequisites

System Requirements

Operating System:

• macOS 10.15 (Catalina) or later
• Windows 10 version 1903 or later (with WSL2 recommended)
• Linux (Ubuntu 18.04+, Debian 10+, or equivalent)

Required Software:

Node.js 18+

Solo Kit requires Node.js version 18 or higher for modern JavaScript features.

Install Node.js:

Option A: Node.js Official Installer

1. Visit nodejs.org
2. Download the LTS version (18+)
3. Run the installer and follow instructions
4. Verify installation: node --version

Option B: Node Version Manager (Recommended)

# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install latest LTS Node.js
nvm install --lts
nvm use --lts

Windows with nvm-windows:

1. Download from github.com/coreybutler/nvm-windows
2. Run installer
3. Open new terminal and run: nvm install lts && nvm use lts

Package Manager: pnpm

Solo Kit uses pnpm for fast, efficient package management.

# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm --version

Git

Required for version control and cloning the repository.

Install Git:

• macOS: xcode-select --install or download from git-scm.com
• Windows: Download from git-scm.com or use winget install Git.Git
• Linux: sudo apt install git (Ubuntu/Debian) or equivalent

Code Editor (Recommended)

While any editor works, these provide the best experience:

Visual Studio Code (Recommended)

• Download from code.visualstudio.com
• Excellent TypeScript support
• Rich extension ecosystem
• Integrated terminal

WebStorm

• Professional IDE with advanced features
• Built-in TypeScript support
• Integrated debugging tools

Cursor

• AI-powered code editor
• Built on VS Code architecture
• Excellent for modern development

🚀 Installation Steps

1. Clone the Repository

# Clone using HTTPS
git clone https://github.com/your-username/solo-kit.git
cd solo-kit

# Or clone using SSH (if you have SSH keys set up)
git clone git@github.com:your-username/solo-kit.git
cd solo-kit

2. Install Dependencies

Solo Kit uses a monorepo structure. One command installs everything:

# Install all dependencies for web, mobile, and shared packages
pnpm install

What this installs:

• Web app dependencies (Next.js, React, etc.)
• Mobile app dependencies (Expo, React Native, etc.)
• Shared package dependencies (UI components, utilities)
• Development tools (ESLint, Prettier, TypeScript, etc.)

Installation time: Usually 2-3 minutes depending on internet speed.

3. Environment Configuration

Solo Kit uses a three-file environment strategy:

# Copy the example environment file
cp .env.example .env.local

Environment Files:

• .env - Safe defaults (committed to git)
• .env.local - Sensitive values (ignored by git)
• .env.example - Documentation (committed to git)

4. Database Setup

Solo Kit requires a PostgreSQL database. Choose one of these options:

Option A: Neon (Recommended)

Free tier: 10GB storage, 1M rows

1. Visit neon.tech
2. Sign up with GitHub or email
3. Create a new project
4. Copy the connection string

# Add to .env.local
DATABASE_URL="postgresql://username:password@ep-xyz.us-east-1.aws.neon.tech/neondb?sslmode=require"

Option B: Supabase

Free tier: 500MB storage, 2 CPUs

1. Visit supabase.com
2. Create a new project
3. Go to Settings > Database
4. Copy the connection string

# Add to .env.local  
DATABASE_URL="postgresql://postgres:password@db.xyz.supabase.co:5432/postgres"

Option C: Railway

Free tier: $5/month credit, no time limit

1. Visit railway.app
2. Create new project > Add PostgreSQL
3. Copy connection string from variables

# Add to .env.local
DATABASE_URL="postgresql://postgres:password@roundhouse.proxy.rlwy.net:12345/railway"

Option D: Local PostgreSQL

For advanced users who prefer local development

Install PostgreSQL:

macOS:

# Using Homebrew
brew install postgresql@15
brew services start postgresql@15

# Create database
createdb solo_kit_dev

Ubuntu/Debian:

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database
sudo -u postgres createdb solo_kit_dev

Windows:

1. Download from postgresql.org
2. Run installer and follow setup wizard
3. Create database using pgAdmin or command line

# Add to .env.local
DATABASE_URL="postgresql://postgres:password@localhost:5432/solo_kit_dev"

5. Initialize Database

Push the database schema to your PostgreSQL database:

pnpm db:push

This command:

• Creates all necessary tables
• Sets up indexes and constraints
• Configures database relationships
• Prepares the database for first use

Expected output:

✓ Schema pushed to database
✓ Tables created: users, accounts, sessions, verification_tokens
✓ Indexes created successfully
✓ Database ready for development

6. Verify Installation

Start the development server to verify everything is working:

pnpm dev

Expected output:

> solo-kit@0.7.1 dev
> pnpm dev:web

> web@0.2.7 dev
> next dev --turbo

▲ Next.js 15.5.2 (Turbopack)
- Local:        http://localhost:3000
- Network:      http://192.168.1.100:3000

✓ Ready in 2.5s

Visit these URLs to verify:

• Main app: http://localhost:3000
• Debug panel: http://localhost:3000/debug

🔧 Optional Configuration

Admin Access Setup

To enable admin features and access /admin routes:

# 1. Add your email to .env.local
echo 'ADMIN_EMAIL="your-email@example.com"' >> .env.local

# 2. Start the app and sign in with that email using OAuth

# 3. Run the admin setup script
pnpm tsx scripts/fix-admin.ts

Email Provider Setup

For development: Email is logged to console by default.

For production: Configure a real email provider.

Resend (Recommended)

1. Sign up at resend.com
2. Create API key
3. Add to .env.local:

EMAIL_PROVIDER="resend"
RESEND_API_KEY="re_abc123..."

SendGrid

1. Sign up at sendgrid.com
2. Create API key
3. Add to .env.local:

EMAIL_PROVIDER="sendgrid"
SENDGRID_API_KEY="SG.abc123..."

Payment Provider Setup

For development: Payments are mocked by default.

For production: Configure payment providers.

Stripe

1. Sign up at stripe.com
2. Get test API keys from dashboard
3. Add to .env.local:

STRIPE_SECRET_KEY="sk_test_your_secret_key_here"
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_your_publishable_key_here"

PayMongo (Southeast Asia)

1. Sign up at paymongo.com
2. Get API keys
3. Add to .env.local:

PAYMONGO_SECRET_KEY="sk_test_abc123..."

OAuth Providers Setup

Configure social login providers:

GitHub OAuth

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Create new OAuth app:
   • Application name: Solo Kit Dev
   • Homepage URL: http://localhost:3000
   • Callback URL: http://localhost:3000/api/auth/callback/github
3. Add to .env.local:

GITHUB_CLIENT_ID="abc123..."
GITHUB_CLIENT_SECRET="def456..."

Google OAuth

1. Go to Google Cloud Console
2. Create new project or select existing
3. Enable Google+ API
4. Create OAuth 2.0 credentials:
   • Authorized origins: http://localhost:3000
   • Authorized redirect URIs: http://localhost:3000/api/auth/callback/google
5. Add to .env.local:

GOOGLE_CLIENT_ID="abc123...apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="def456..."

🏗️ Project Structure Verification

After installation, your project should look like this:

solo-kit/
├── apps/
│   ├── web/                 # Next.js web application
│   │   ├── app/            # App router pages
│   │   ├── components/     # React components
│   │   ├── lib/           # Utilities and configurations
│   │   └── package.json   # Web app dependencies
│   └── mobile/            # Expo mobile application
│       ├── app/           # Mobile app screens
│       ├── components/    # Mobile components
│       └── package.json   # Mobile app dependencies
├── packages/
│   ├── ui/               # Shared UI components
│   ├── utils/            # Shared utilities
│   ├── database/         # Database schema and operations
│   └── eslint-config/    # Shared ESLint configuration
├── .env                  # Safe defaults (committed)
├── .env.local           # Your sensitive config (ignored)
├── .env.example         # Documentation
├── package.json         # Root package configuration
├── pnpm-workspace.yaml  # Workspace configuration
└── turbo.json          # Build system configuration

✅ Verification Checklist

Ensure everything is working correctly:

✅ Basic Functionality

• node --version shows 18+
• pnpm --version works
• pnpm dev starts without errors
• http://localhost:3000 loads the landing page
• Database connection works (check /debug)

✅ Database Features

• pnpm db:studio opens Drizzle Studio
• Can create user account via sign-up form
• User data appears in database
• Authentication redirects work

✅ Development Tools

• Hot reloading works when editing files
• TypeScript errors show in terminal
• pnpm lint runs without errors
• pnpm type-check passes

✅ Optional Features (if configured)

• Email provider works (test with sign-up)
• OAuth providers work (test sign-in)
• Payment provider loads (check /debug)
• Admin access works (if ADMIN_EMAIL set)

🐛 Troubleshooting Installation

Common Issues and Solutions

Node.js Version Error

Error: This package requires Node.js version 18 or higher

Solution: Install Node.js 18+ using the methods above.

pnpm Not Found

pnpm: command not found

Solution: Install pnpm globally: npm install -g pnpm

Database Connection Failed

Error: Connection terminated unexpectedly

Solutions:

1. Verify DATABASE_URL format is correct
2. Check database server is running
3. Ensure firewall allows connections
4. For cloud databases, verify IP whitelist

Port Already in Use

Error: Port 3000 is already in use

Solutions:

1. Kill process using port: lsof -ti:3000 | xargs kill
2. Use different port: PORT=3001 pnpm dev
3. Find and stop conflicting application

Permission Errors (macOS/Linux)

EACCES: permission denied

Solutions:

1. Use Node version manager instead of sudo
2. Fix npm permissions: npm config set prefix ~/.npm-global
3. Add to PATH: export PATH=~/.npm-global/bin:$PATH

Windows WSL Issues

Solutions:

1. Use WSL2 instead of WSL1
2. Install Node.js inside WSL, not Windows
3. Clone repository inside WSL filesystem

Getting Help

If you're still having issues:

1. Check the debug panel at http://localhost:3000/debug
2. Search existing issues on GitHub
3. Create new issue with:
   • Operating system and version
   • Node.js version (node --version)
   • pnpm version (pnpm --version)
   • Complete error message
   • Steps you've tried

🎉 Next Steps

Great! You now have Solo Kit fully installed and configured. Continue with:

1. Project Structure - Understand the codebase organization
2. Editor Setup - Configure your editor for the best experience
3. Development - Learn the development workflow
4. Database Guide - Master the database layer

🔄 Updating Solo Kit

To update to a newer version of Solo Kit:

# Pull latest changes
git pull origin main

# Update dependencies
pnpm install

# Update database schema if needed
pnpm db:push

# Check for any breaking changes in CHANGELOG.md

Always review the changelog before updating to understand any breaking changes or new features.