Getting Started

Quick setup and first steps with Izri

Welcome! This section has everything you need to get Izri running and make your first contribution.

📋 Prerequisites

Before you start, ensure you have:

• Node.js 18+ - Install
• pnpm 8+ - npm install -g pnpm
• Docker & Docker Compose - Install
• Git - Install
• Python 3.11+ (for AI service) - Install

Verify your setup:

node --version      # v18+
pnpm --version      # 8+
docker --version    # 20+
git --version       # 2+
python3 --version   # 3.11+

🚀 Quick Start (5 Minutes)

# 1. Clone repository
git clone https://github.com/your-org/izri.git
cd izri

# 2. Install dependencies
pnpm install

# 3. Setup environment
cp .env.shared.example .env.shared
pnpm env:generate

# 4. Start infrastructure
pnpm dev:docker

# 5. Setup database
pnpm db:generate
pnpm db:migrate
pnpm db:seed

# 6. Start all services
pnpm dev

That's it! 🎉

🌐 Access Your Services

Verify Everything Works

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

# Web dashboard
# Open http://localhost:5173 in browser
# Try signing in with any email/password (mock auth enabled)

📚 Documentation

• Detailed Setup - Step-by-step installation guide

🎯 Next Steps

1. Complete Setup - Follow the detailed Quick Start Guide
2. Learn Architecture - Check Architecture Overview
3. Start Developing - Review Development Guide

🆘 Troubleshooting

Port Already in Use

# Kill process using port
lsof -ti:5173 | xargs kill -9  # Web
lsof -ti:4000 | xargs kill -9  # API
lsof -ti:8000 | xargs kill -9  # AI

Database Connection Failed

# Restart Docker services
pnpm docker:down
pnpm dev:docker

# Verify DATABASE_URL in .env
cat apps/api/.env | grep DATABASE_URL

pnpm install Fails

# Clear cache and reinstall
pnpm store prune
rm -rf node_modules
pnpm install

Python AI Service Error

cd packages/ai-service
python3 -m pip install -r requirements.txt
python3 main.py

⚙️ Environment Variables

Essential variables in .env.shared:

# Database
DATABASE_URL="postgresql://postgres:password@localhost:5433/izri"

# API
API_PORT=4000
API_URL="http://localhost:4000"
VITE_API_URL="http://localhost:4000"

# AI Service
AI_SERVICE_URL="http://localhost:8000"

# Optional (for later)
# GITHUB_CLIENT_ID="..."
# OPENAI_API_KEY="..."

Run pnpm env:generate after editing .env.shared to generate project-specific env files.

Ready to dive in? Start with the Detailed Quick Start Guide →