Chalkboard.id Deployment & Usage Guide

1. Prerequisites

Required Tools

Bun (v1.0+) — Primary runtime and package manager
Node.js (v20+) — For Next.js 15 compatibility
Git — Version control
PostgreSQL (v14+) — Required for Docker/Cloud deployments (not needed for Desktop mode)

For Desktop Development

Rust (v1.70+) — Required for Tauri v2 builds
Platform-specific dependencies:
- macOS: Xcode Command Line Tools
- Windows: Microsoft Visual C++ Build Tools
- Linux: libwebkit2gtk-4.1-dev, build-essential, curl, wget, libssl-dev, libgtk-3-dev, libayatana-appindicator3-dev, librsvg2-dev

Accounts (Optional)

Railway account — For one-click cloud deployment
Neon Database — For serverless PostgreSQL (Vercel Edge)
Midtrans account — For payment gateway integration (optional)

2. Installation

Clone Repository

git clone https://github.com/kugie-app/chalkboard.id.git
cd chalkboard.id

Install Dependencies

# Install JavaScript/TypeScript dependencies
bun install

# Install Rust dependencies (for desktop builds)
cd src-tauri && cargo fetch && cd ..

Database Setup

# Run database migrations (Drizzle ORM)
bun drizzle-kit migrate

# Seed database with sample data (optional)
bun tsx src/lib/seed.ts

3. Configuration

Create .env.local in the project root:

# Database Configuration
DATABASE_URL="postgresql://user:password@localhost:5432/chalkboard"
# For Desktop/PGlite mode: DATABASE_URL="file:./local.db"

# NextAuth.js Configuration
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-random-secret-key-min-32-chars"

# Optional: Payment Integration
MIDTRANS_SERVER_KEY="your-midtrans-server-key"
MIDTRANS_CLIENT_KEY="your-midtrans-client-key"

# Optional: Analytics & Monitoring
ANALYTICS_API_KEY="your-analytics-key"

System Settings Configuration

The application uses database-driven settings (see src/lib/seed.ts):

billing_rate_type: Set to hourly or per_minute
Default table rates are seeded automatically

4. Build & Run

Development Mode (Web)

# Start Next.js development server
bun dev
# Access at http://localhost:3000

Development Mode (Desktop)

# Run Tauri development build with hot reload
bun tauri dev

Production Build

Web Application:

# Build optimized production bundle
bun next build

# Start production server
bun next start

Desktop Application:

# Build desktop installers for current platform
bun tauri build

# Output locations:
# - macOS: src-tauri/target/release/bundle/dmg/*.dmg
# - Windows: src-tauri/target/release/bundle/msi/*.msi
# - Linux: src-tauri/target/release/bundle/deb/*.deb

Database Management Commands

# Generate new migration after schema changes
bun drizzle-kit generate

# Push schema changes directly (development only)
bun drizzle-kit push

# Open Drizzle Studio (database GUI)
bun drizzle-kit studio

5. Deployment

Option A: Desktop App (Recommended for Single Location)

No external database or server required.

Download platform-specific installer from GitHub Releases
Install and launch — PGlite embedded database initializes automatically
Access via localhost:3000 within the desktop window
Auto-updates enabled by default

Option B: Docker (Self-Hosted)

# Quick start with official image
docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:pass@db:5432/chalkboard" \
  -e NEXTAUTH_SECRET="your-secret" \
  kugieapp/chalkboard:latest

# Or use Docker Compose for full stack
docker compose up -d

Docker Compose Requirements:

PostgreSQL container (v14+)
Volume mounts for persistent storage
Environment variables as listed in Configuration section

Option C: Railway (Cloud)

Click deploy button above
Railway automatically provisions PostgreSQL database
Set NEXTAUTH_SECRET in Railway Variables
Deploy completes with automatic HTTPS

Option D: Vercel Edge (Serverless)

Connect GitHub repo to Vercel
Add Neon PostgreSQL integration
Configure environment variables in Vercel Dashboard
Deploy with bun vercel --prod

Note: For Vercel Edge, use Neon Database connection pooling:

DATABASE_URL="postgresql://user:pass@pooler.neon.tech/chalkboard?sslmode=require"

6. Troubleshooting

Database Connection Issues

Symptom: Error: connect ECONNREFUSED 127.0.0.1:5432

Solution: Ensure PostgreSQL is running: sudo service postgresql start (Linux) or brew services start postgresql (macOS)
Desktop mode: Verify PGlite directory permissions in ~/.config/chalkboard/

Migration Failures

Symptom: Migration failed: relation already exists

# Reset migrations (WARNING: Destroys data)
bun drizzle-kit drop
bun drizzle-kit migrate

# Or check migration status
bun tsx -e "import { getCurrentDatabaseVersion } from './src/lib/migration-manager'; console.log(await getCurrentDatabaseVersion());"

Tauri Build Errors

Symptom: error: could not compile tauri-app

macOS: Install Xcode Command Line Tools: xcode-select --install
Windows: Install Visual Studio Build Tools with "Desktop development with C++" workload
Linux: Install dependencies: sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev

Authentication Errors

Symptom: JWT must have 3 parts or session errors

Ensure NEXTAUTH_SECRET is at least 32 characters
Verify NEXTAUTH_URL matches your actual domain (no trailing slash)
Clear browser cookies for the domain

Port Already in Use

Symptom: Port 3000 is already in use

# Find and kill process
lsof -ti:3000 | xargs kill -9

# Or use different port
bun dev -- -p 3001

Permission Denied (Linux Desktop)

Symptom: AppImage or binary won't execute

chmod +x chalkboard_1.0.3_amd64.AppImage
# Or for .deb installs:
sudo dpkg -i chalkboard_1.0.3_amd64.deb
sudo apt-get install -f  # Fix dependencies if needed

Analytics API 401 Errors

Symptom: Revenue dashboard shows "Unauthorized"

Verify user has appropriate role in staff table
Check CASL permissions in database
Re-authenticate: Sign out and sign back in

Data Seeding Issues

If seed fails partially:

# Truncate and re-seed
bun tsx -e "
import { db } from './src/lib/db';
import { sql } from 'drizzle-orm';
await db.execute(sql\`TRUNCATE TABLE tables, fnb_categories, fnb_items, staff CASCADE\`);
"
bun tsx src/lib/seed.ts

How to Deploy & Use chalkboard.id