initial setup
This commit is contained in:
446
docs/development_setup.md
Normal file
446
docs/development_setup.md
Normal file
@@ -0,0 +1,446 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user