446 lines
11 KiB
Markdown
446 lines
11 KiB
Markdown
# JobForge MVP - Development Setup Guide
|
|
|
|
**Version:** 1.0.0 MVP
|
|
**Target Audience:** Developers
|
|
**Last Updated:** July 2025
|
|
|
|
---
|
|
|
|
## 🎯 Prerequisites
|
|
|
|
### Required Software
|
|
- **Docker Desktop** 4.20+ with Docker Compose
|
|
- **Git** 2.30+
|
|
- **Text Editor** (VS Code recommended)
|
|
- **API Keys** (Claude, OpenAI)
|
|
|
|
### System Requirements
|
|
- **RAM:** 8GB minimum (Docker containers + database)
|
|
- **Storage:** 10GB free space
|
|
- **OS:** Windows 10+, macOS 12+, or Linux
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start (5 Minutes)
|
|
|
|
### 1. Clone Repository
|
|
```bash
|
|
git clone https://github.com/your-org/jobforge-mvp.git
|
|
cd jobforge-mvp
|
|
```
|
|
|
|
### 2. Environment Configuration
|
|
```bash
|
|
# Copy environment template
|
|
cp .env.example .env
|
|
|
|
# Edit .env file with your API keys
|
|
nano .env # or use your preferred editor
|
|
```
|
|
|
|
**Required Environment Variables:**
|
|
```bash
|
|
# API Keys (REQUIRED)
|
|
CLAUDE_API_KEY=your_claude_api_key_here
|
|
OPENAI_API_KEY=your_openai_api_key_here
|
|
|
|
# Database (Auto-configured for local development)
|
|
DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
|
|
|
|
# JWT Secret (Generate random string)
|
|
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
|
|
|
|
# Development Settings
|
|
DEBUG=true
|
|
LOG_LEVEL=INFO
|
|
```
|
|
|
|
### 3. Start Development Environment
|
|
```bash
|
|
# Start all services (PostgreSQL, Backend, Frontend)
|
|
docker-compose up -d
|
|
|
|
# View logs to ensure everything started correctly
|
|
docker-compose logs -f
|
|
```
|
|
|
|
### 4. Verify Installation
|
|
- **Frontend:** http://localhost:8501
|
|
- **Backend API:** http://localhost:8000
|
|
- **API Documentation:** http://localhost:8000/docs
|
|
- **Database:** localhost:5432
|
|
|
|
---
|
|
|
|
## 🔧 Detailed Setup Instructions
|
|
|
|
### Getting API Keys
|
|
|
|
#### Claude API Key
|
|
1. Visit https://console.anthropic.com/
|
|
2. Create account or log in
|
|
3. Go to "API Keys" section
|
|
4. Create new key with name "JobForge Development"
|
|
5. Copy key to `.env` file
|
|
|
|
#### OpenAI API Key
|
|
1. Visit https://platform.openai.com/api-keys
|
|
2. Create account or log in
|
|
3. Click "Create new secret key"
|
|
4. Name it "JobForge Development"
|
|
5. Copy key to `.env` file
|
|
|
|
### Environment File Setup
|
|
```bash
|
|
# .env file (copy from .env.example)
|
|
|
|
# =============================================================================
|
|
# API KEYS - REQUIRED FOR DEVELOPMENT
|
|
# =============================================================================
|
|
CLAUDE_API_KEY=sk-ant-api03-xxx...
|
|
OPENAI_API_KEY=sk-xxx...
|
|
|
|
# =============================================================================
|
|
# DATABASE CONFIGURATION
|
|
# =============================================================================
|
|
DATABASE_URL=postgresql+asyncpg://jobforge_user:jobforge_password@postgres:5432/jobforge_mvp
|
|
POSTGRES_DB=jobforge_mvp
|
|
POSTGRES_USER=jobforge_user
|
|
POSTGRES_PASSWORD=jobforge_password
|
|
|
|
# =============================================================================
|
|
# AUTHENTICATION
|
|
# =============================================================================
|
|
JWT_SECRET_KEY=super-secret-jwt-key-minimum-32-characters-long
|
|
JWT_ALGORITHM=HS256
|
|
JWT_EXPIRE_HOURS=24
|
|
|
|
# =============================================================================
|
|
# APPLICATION SETTINGS
|
|
# =============================================================================
|
|
DEBUG=true
|
|
LOG_LEVEL=INFO
|
|
BACKEND_URL=http://backend:8000
|
|
|
|
# =============================================================================
|
|
# AI PROCESSING SETTINGS
|
|
# =============================================================================
|
|
CLAUDE_MODEL=claude-sonnet-4-20250514
|
|
OPENAI_EMBEDDING_MODEL=text-embedding-3-large
|
|
MAX_PROCESSING_TIME_SECONDS=120
|
|
```
|
|
|
|
---
|
|
|
|
## 🐳 Docker Setup
|
|
|
|
### Docker Compose Configuration
|
|
The `docker-compose.yml` file configures three main services:
|
|
|
|
#### PostgreSQL Database
|
|
- **Port:** 5432
|
|
- **Database:** jobforge_mvp
|
|
- **Extensions:** pgvector for AI embeddings
|
|
- **Data:** Persisted in Docker volume
|
|
|
|
#### Backend API (FastAPI)
|
|
- **Port:** 8000
|
|
- **Auto-reload:** Enabled for development
|
|
- **API Docs:** http://localhost:8000/docs
|
|
|
|
#### Frontend App (Dash)
|
|
- **Port:** 8501
|
|
- **Auto-reload:** Enabled for development
|
|
|
|
### Docker Commands
|
|
|
|
#### Start Services
|
|
```bash
|
|
# Start all services in background
|
|
docker-compose up -d
|
|
|
|
# Start with logs visible
|
|
docker-compose up
|
|
|
|
# Start specific service
|
|
docker-compose up backend
|
|
```
|
|
|
|
#### View Logs
|
|
```bash
|
|
# All services logs
|
|
docker-compose logs -f
|
|
|
|
# Specific service logs
|
|
docker-compose logs -f backend
|
|
docker-compose logs -f frontend
|
|
docker-compose logs -f postgres
|
|
```
|
|
|
|
#### Stop Services
|
|
```bash
|
|
# Stop all services
|
|
docker-compose down
|
|
|
|
# Stop and remove volumes (WARNING: Deletes database data)
|
|
docker-compose down -v
|
|
```
|
|
|
|
#### Rebuild Services
|
|
```bash
|
|
# Rebuild after code changes
|
|
docker-compose build
|
|
|
|
# Rebuild specific service
|
|
docker-compose build backend
|
|
|
|
# Rebuild and restart
|
|
docker-compose up --build
|
|
```
|
|
|
|
---
|
|
|
|
## 🗄️ Database Setup
|
|
|
|
### Automatic Database Initialization
|
|
The database is automatically set up when you first run `docker-compose up`:
|
|
|
|
1. **PostgreSQL starts** with pgvector extension
|
|
2. **Database created** with name `jobforge_mvp`
|
|
3. **Tables created** from `database/init.sql`
|
|
4. **Row Level Security** policies applied
|
|
5. **Sample data** inserted (optional)
|
|
|
|
### Manual Database Operations
|
|
|
|
#### Connect to Database
|
|
```bash
|
|
# Connect via Docker
|
|
docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp
|
|
|
|
# Connect from host (if PostgreSQL client installed)
|
|
psql -h localhost -p 5432 -U jobforge_user -d jobforge_mvp
|
|
```
|
|
|
|
#### Reset Database
|
|
```bash
|
|
# WARNING: This deletes all data
|
|
docker-compose down -v
|
|
docker-compose up -d postgres
|
|
```
|
|
|
|
#### Database Migrations (Future)
|
|
```bash
|
|
# When Alembic is added
|
|
docker-compose exec backend alembic upgrade head
|
|
```
|
|
|
|
### Database Schema Verification
|
|
After startup, verify tables exist:
|
|
```sql
|
|
-- Connect to database and run:
|
|
\dt
|
|
|
|
-- Expected tables:
|
|
-- users
|
|
-- applications
|
|
-- documents
|
|
-- user_resumes
|
|
-- document_embeddings
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 Development Workflow
|
|
|
|
### Code Organization
|
|
```
|
|
src/
|
|
├── backend/ # FastAPI backend code
|
|
│ ├── main.py # FastAPI app entry point
|
|
│ ├── api/ # API route handlers
|
|
│ ├── services/ # Business logic
|
|
│ ├── database/ # Database models and connection
|
|
│ └── models/ # Pydantic request/response models
|
|
├── frontend/ # Dash frontend code
|
|
│ ├── main.py # Dash app entry point
|
|
│ ├── components/ # Reusable UI components
|
|
│ ├── pages/ # Page components
|
|
│ └── api_client/ # Backend API client
|
|
├── agents/ # AI processing agents
|
|
└── helpers/ # Shared utilities
|
|
```
|
|
|
|
### Making Code Changes
|
|
|
|
#### Backend Changes
|
|
1. **Modify code** in `src/backend/`
|
|
2. **FastAPI auto-reloads** automatically
|
|
3. **Test changes** at http://localhost:8000/docs
|
|
|
|
#### Frontend Changes
|
|
1. **Modify code** in `src/frontend/`
|
|
2. **Dash auto-reloads** automatically
|
|
3. **Test changes** at http://localhost:8501
|
|
|
|
#### Database Changes
|
|
1. **Modify** `database/init.sql`
|
|
2. **Reset database:** `docker-compose down -v && docker-compose up -d`
|
|
|
|
### Testing Your Setup
|
|
|
|
#### 1. Backend Health Check
|
|
```bash
|
|
curl http://localhost:8000/health
|
|
# Expected: {"status": "healthy", "service": "jobforge-backend"}
|
|
```
|
|
|
|
#### 2. Database Connection
|
|
```bash
|
|
curl http://localhost:8000/api/v1/auth/me
|
|
# Expected: {"detail": "Not authenticated"} (this is correct - no token)
|
|
```
|
|
|
|
#### 3. Frontend Access
|
|
Visit http://localhost:8501 - should see login page
|
|
|
|
#### 4. API Documentation
|
|
Visit http://localhost:8000/docs - should see Swagger UI
|
|
|
|
---
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### "Port already in use"
|
|
```bash
|
|
# Check what's using the port
|
|
lsof -i :8501 # or :8000, :5432
|
|
|
|
# Kill the process or change ports in docker-compose.yml
|
|
```
|
|
|
|
#### "API Key Invalid"
|
|
```bash
|
|
# Verify API key format
|
|
echo $CLAUDE_API_KEY # Should start with "sk-ant-api03-"
|
|
echo $OPENAI_API_KEY # Should start with "sk-"
|
|
|
|
# Test API key manually
|
|
curl -H "Authorization: Bearer $CLAUDE_API_KEY" https://api.anthropic.com/v1/messages
|
|
```
|
|
|
|
#### "Database Connection Failed"
|
|
```bash
|
|
# Check if PostgreSQL is running
|
|
docker-compose ps postgres
|
|
|
|
# Check database logs
|
|
docker-compose logs postgres
|
|
|
|
# Try connecting manually
|
|
docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp
|
|
```
|
|
|
|
#### "Frontend Won't Load"
|
|
```bash
|
|
# Check frontend logs
|
|
docker-compose logs frontend
|
|
|
|
# Common issue: Backend not ready
|
|
curl http://localhost:8000/health
|
|
|
|
# Restart frontend
|
|
docker-compose restart frontend
|
|
```
|
|
|
|
#### "AI Processing Fails"
|
|
```bash
|
|
# Check backend logs for API errors
|
|
docker-compose logs backend | grep -i error
|
|
|
|
# Verify API keys are loaded
|
|
docker-compose exec backend env | grep API_KEY
|
|
```
|
|
|
|
### Development Tips
|
|
|
|
#### Hot Reloading
|
|
- Both backend and frontend support hot reloading
|
|
- Database schema changes require full restart
|
|
- Environment variable changes require restart
|
|
|
|
#### Debugging
|
|
```bash
|
|
# Backend debugging with detailed logs
|
|
DEBUG=true LOG_LEVEL=DEBUG docker-compose up backend
|
|
|
|
# Frontend debugging
|
|
docker-compose exec frontend python src/frontend/main.py --debug
|
|
```
|
|
|
|
#### Performance Monitoring
|
|
```bash
|
|
# View container resource usage
|
|
docker stats
|
|
|
|
# View database performance
|
|
docker-compose exec postgres pg_stat_activity
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Development Tools
|
|
|
|
### Recommended VS Code Extensions
|
|
- **Python** (Microsoft)
|
|
- **Docker** (Microsoft)
|
|
- **PostgreSQL** (Chris Kolkman)
|
|
- **REST Client** (Huachao Mao)
|
|
- **GitLens** (GitKraken)
|
|
|
|
### API Testing Tools
|
|
- **Built-in Swagger UI:** http://localhost:8000/docs
|
|
- **curl commands** (see API specification)
|
|
- **Postman** (import OpenAPI spec from `/openapi.json`)
|
|
|
|
### Database Tools
|
|
- **pgAdmin** (web-based PostgreSQL admin)
|
|
- **DBeaver** (database IDE)
|
|
- **psql** (command line client)
|
|
|
|
---
|
|
|
|
## 🚀 Next Steps
|
|
|
|
Once your environment is running:
|
|
|
|
1. **Create test account** at http://localhost:8501
|
|
2. **Review API documentation** at http://localhost:8000/docs
|
|
3. **Follow Database Design** document for schema details
|
|
4. **Check Testing Strategy** document for testing approach
|
|
5. **Start development** following the 8-week roadmap
|
|
|
|
---
|
|
|
|
## 📞 Getting Help
|
|
|
|
### Development Issues
|
|
- Check this troubleshooting section first
|
|
- Review Docker logs: `docker-compose logs`
|
|
- Verify environment variables: `docker-compose exec backend env`
|
|
|
|
### API Issues
|
|
- Use Swagger UI for interactive testing
|
|
- Check API specification document
|
|
- Verify authentication headers
|
|
|
|
### Database Issues
|
|
- Connect directly: `docker-compose exec postgres psql -U jobforge_user -d jobforge_mvp`
|
|
- Check database logs: `docker-compose logs postgres`
|
|
- Review database design document
|
|
|
|
---
|
|
|
|
*This setup guide should get you from zero to a working development environment in under 10 minutes. If you encounter issues not covered here, please update this document for future developers.* |