Quick Start Guide

Complete step-by-step setup instructions

This guide provides detailed instructions for setting up Izri. For a faster overview, see the Getting Started page.

📋 Prerequisites

Ensure you have installed:

Node.js 18+
pnpm 8+
Docker & Docker Compose
Git
Python 3.11+ (for AI service)

1️⃣ Clone Repository

# Using HTTPS
git clone https://github.com/your-org/izri.git
cd izri

# Or using SSH (if configured)
git clone git@github.com:your-org/izri.git
cd izri

2️⃣ Install Dependencies

pnpm install

This installs all dependencies for the monorepo and links workspace packages together. Time: 2-5 minutes

Troubleshoot

# Clear cache if it fails
pnpm store prune
pnpm install

# Or full reset
rm -rf node_modules
pnpm install

3️⃣ Configure Environment

# Copy example file
cp .env.shared.example .env.shared

# Edit with your values (most defaults work for local dev)
# nano .env.shared  # or use your editor

# Generate project-specific .env files
pnpm env:generate

Key variables (defaults work for local development):

DATABASE_URL="postgresql://postgres:password@localhost:5433/izri"
API_URL="http://localhost:4000"
VITE_API_URL="http://localhost:4000"
AI_SERVICE_URL="http://localhost:8000"

Run pnpm env:generate whenever you edit .env.shared

4️⃣ Start Infrastructure

pnpm dev:docker

This starts PostgreSQL (port 5433) and Redis (port 6379) in Docker containers.

Verify:

docker ps
# Should show postgres and redis containers

5️⃣ Setup Database

# Generate migrations from schema
pnpm db:generate

# Apply migrations
pnpm db:migrate

# Seed with test data
pnpm db:seed

Verify:

pnpm db:studio
# Opens http://localhost:4983 - visual database explorer
# You should see tables: users, projects, organizations, test_runs, etc.

6️⃣ Start All Services

pnpm dev

This starts:

Web: http://localhost:5173 (React Router + Vite)
API: http://localhost:4000 (Hono + tRPC)
AI: http://localhost:8000 (FastAPI)

Expected output:

@izri/web:dev: VITE v5.0.0  ready in 1234 ms
@izri/web:dev: ➜  Local:   http://localhost:5173/
@izri/api:dev: 🚀 Server running on http://localhost:4000
ai-service:dev: INFO:     Uvicorn running on http://localhost:8000

✅ Verify Setup

API Health

curl http://localhost:4000/health
# Expected: {"ok":true}

Web Dashboard

Open http://localhost:5173
Click "Sign In with GitHub"
Authorise the OAuth app (requires GITHUB_CLIENT_ID + GITHUB_CLIENT_SECRET in .env.shared)
You should be redirected back and see the dashboard

Need a GitHub OAuth app? See docs/setup/GITHUB_OAUTH.md for setup instructions.

Database

pnpm db:studio
# Visual database explorer at http://localhost:4983

🎯 Next Steps

Learn: Check Architecture Overview
Develop: See Development Guide

🆘 Common Issues

Issue	Solution
Port in use	`lsof -ti:5173 \| xargs kill -9`
DB connection failed	`pnpm docker:down && pnpm dev:docker`
`pnpm install` fails	`pnpm store prune && pnpm install`
Python errors	`cd packages/ai-service && pip install -r requirements.txt`

📚 All Commands

Development:

pnpm dev              # Start all services
pnpm dev:web          # Start web only
pnpm dev:api          # Start API only
pnpm dev:docker       # Start Docker services (PostgreSQL, Redis)

Database:

pnpm db:studio        # Open database UI
pnpm db:generate      # Generate migrations
pnpm db:migrate       # Apply migrations
pnpm db:seed          # Seed test data

Build & Quality:

pnpm build            # Build all packages
pnpm lint             # Lint code
pnpm format:all       # Format code
pnpm type:check       # Check types
pnpm test             # Run tests
pnpm clean            # Clean build artifacts

Continue with the Architecture Overview to understand the system →