Getting Started

This guide walks you through setting up Open Genie for local development.

Prerequisites

• Node.js 20+
• PostgreSQL 14+ (running and accessible)
• Ollama installed and running (ollama.com)
• FFmpeg installed (required for video thumbnails and camera captures)

1. Clone and Install

git clone <repo-url> open-genie
cd open-genie
npm install

2. Environment Variables

Create a .env file in apps/web/:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/open_genie

# Secrets
AUTH_SECRET=your-session-signing-secret       # min 32 chars — signs web session cookies
GENIE_JWT_SECRET=your-jwt-secret-min-32-chars # signs device access/refresh tokens

# Ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_DEFAULT_MODEL=granite4:350m
OLLAMA_VISION_MODEL=llava:latest

# Storage
GENIE_STORAGE_PATH=./data/files

# Server
PORT=3000
NODE_ENV=development

# Google OAuth (for web UI sign-in — optional in dev)
AUTH_GOOGLE_ID=your-google-client-id
AUTH_GOOGLE_SECRET=your-google-client-secret

# Push Notifications (optional)
# FIREBASE_SERVICE_ACCOUNT=path/to/firebase-service-account.json
# EXPO_ACCESS_TOKEN=your-expo-access-token

Required Variables

Variable	Description
DATABASE_URL	PostgreSQL connection string
AUTH_SECRET	Secret for signing web session cookies (min 32 chars)
GENIE_JWT_SECRET	Secret for signing device JWT tokens (min 32 chars)

Optional Variables

Variable	Default	Description
OLLAMA_BASE_URL	http://localhost:11434	Ollama server URL
OLLAMA_DEFAULT_MODEL	granite4:350m	Default chat model
OLLAMA_VISION_MODEL	llava:latest	Vision analysis model
GENIE_STORAGE_PATH	./data/files	File storage root directory
PORT	3000	Server port

3. Database Setup

Generate and run migrations:

# Generate migration files from the schema
npm run db:generate

# Apply migrations to the database
npm run db:migrate

To explore the database interactively:

npm run db:studio

This opens Drizzle Studio in your browser.

4. Pull Ollama Models

Make sure you have the required models downloaded:

ollama pull granite4:350m    # Default chat model
ollama pull llava:latest     # Vision model (for camera analysis)

5. Start the Dev Server

npm run web:dev

This runs two processes concurrently:

• Hono API server on http://localhost:3000 (tsx watch server.ts)
• Vite dev server on http://localhost:5173 with HMR

In development, point your browser to the Vite dev server (http://localhost:5173). It proxies /api/* requests to the Hono server automatically.

6. Verify

Open http://localhost:5173 in your browser to access the web UI (or http://localhost:3000/api/status to check the backend directly).

Check the health endpoint:

curl http://localhost:3000/api/status

npm Scripts (from repo root)

Script	Description
npm run web:dev	Start dev server with HMR (Hono + Vite concurrently)
npm run web:build	Build for production (Vite SPA + server bundle)
npm run web:start	Start production server
npm run db:migrate	Run pending migrations
npm run db:studio	Open Drizzle Studio GUI

From apps/web/ directly

Script	Description
npm run dev	Same as web:dev
npm run build	Build both client (vite build) and server (tsc)
npm run start	Production: tsx server.ts
npm run db:generate	Generate Drizzle migration files from schema
npm run db:migrate	Apply pending migrations
npm run db:push	Push schema directly (skip migrations, dev only)
npm run db:studio	Open Drizzle Studio GUI
npm run preflight	Run preflight checks and print a status report