Quickstart

Get InterviewGuide running locally in minutes. Complete setup guide for development environment.

This guide will help you set up and run InterviewGuide locally for development. You’ll have a fully functional AI interview platform with resume analysis, mock interviews, and RAG-based knowledge base.

Prerequisites

Before you begin, ensure you have the following installed:

Dependency	Version	Required	Notes
JDK	21+	Yes	OpenJDK recommended
Node.js	18+	Yes	For frontend development
PostgreSQL	14+	Yes	With pgvector extension
Redis	6+	Yes	For caching and message queues
S3-compatible storage	-	Yes	MinIO or RustFS

Looking for a simpler setup? If you prefer Docker, check out the Docker Deployment guide for a one-command installation.

Step 1: Clone the Repository

1. Clone and navigate to project

   git clone https://github.com/Snailclimb/interview-guide.git
   cd interview-guide
   

Step 2: Database Setup

1. Create PostgreSQL database

   Connect to your PostgreSQL instance and create the database:

   CREATE DATABASE interview_guide;
   
2. Enable pgvector extension

   Connect to the newly created database and enable the vector extension:

   \c interview_guide
   CREATE EXTENSION IF NOT EXISTS vector;
   

   The pgvector extension is required for vector similarity search in the knowledge base feature. If you skip this step, Spring AI will automatically create it on first startup when initialize-schema: true.

Step 3: Redis Setup

Ensure Redis is running on your local machine:

# Start Redis (if using Homebrew on macOS)
brew services start redis

# Or start Redis directly
redis-server

# Verify Redis is running
redis-cli ping
# Should return: PONG

Step 4: Configure S3-Compatible Storage

You can use either MinIO (recommended for local development) or RustFS:

MinIO (Docker)

docker run -d \
  -p 9000:9000 \
  -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  --name minio \
  minio/minio server /data --console-address ":9001"

# Create the bucket
docker run --rm --network host minio/mc \
  bash -c "mc alias set myminio http://localhost:9000 minioadmin minioadmin && \
           mc mb myminio/interview-guide && \
           mc anonymous set public myminio/interview-guide"

Step 5: Configure Application

1. Set AI API Key

   The platform uses Alibaba Cloud DashScope for AI capabilities. Set your API key as an environment variable:

   export AI_BAILIAN_API_KEY=your_api_key_here
   

   Get Your API Key

   Apply for a DashScope API key from Alibaba Cloud Bailian platform

2. Update application.yml

   Edit app/src/main/resources/application.yml to match your local environment:

   app/src/main/resources/application.yml

   spring:
     # PostgreSQL database configuration
     datasource:
       url: jdbc:postgresql://${POSTGRES_HOST:localhost}:${POSTGRES_PORT:5432}/${POSTGRES_DB:interview_guide}
       username: ${POSTGRES_USER:postgres}
       password: ${POSTGRES_PASSWORD:123456}
       driver-class-name: org.postgresql.Driver
   
     jpa:
       hibernate:
         ddl-auto: create  # Use 'create' for first run, then change to 'update'
       show-sql: false
   
     # Redis configuration using Redisson
     redis:
       redisson:
         config: |
           singleServerConfig:
             address: "redis://${REDIS_HOST:localhost}:${REDIS_PORT:6379}"
             database: 0
             connectionMinimumIdleSize: 10
             connectionPoolSize: 64
   
     # Spring AI - Alibaba Cloud DashScope (OpenAI-compatible mode)
     ai:
       openai:
         base-url: https://dashscope.aliyuncs.com/compatible-mode
         api-key: ${AI_BAILIAN_API_KEY}
         chat:
           options:
             model: ${AI_MODEL:qwen-plus}
             temperature: 0.2
         embedding:
           options:
             model: text-embedding-v3
       
       # PostgreSQL Vector Store configuration
       vectorstore:
         pgvector:
           index-type: HNSW
           distance-type: COSINE_DISTANCE
           dimensions: 1024  # text-embedding-v3 dimension
           initialize-schema: true   # Set to 'true' for dev, 'false' for production
           remove-existing-vector-store-table: false
   
   # Application custom configuration
   app:
     # S3-compatible storage configuration
     storage:
       endpoint: ${APP_STORAGE_ENDPOINT:http://localhost:9000}
       access-key: ${APP_STORAGE_ACCESS_KEY:minioadmin}
       secret-key: ${APP_STORAGE_SECRET_KEY:minioadmin}
       bucket: ${APP_STORAGE_BUCKET:interview-guide}
       region: ${APP_STORAGE_REGION:us-east-1}
     
     # Interview configuration
     interview:
       follow-up-count: ${APP_INTERVIEW_FOLLOW_UP_COUNT:1}  # Number of follow-up questions per main question
       evaluation:
         batch-size: ${APP_INTERVIEW_EVALUATION_BATCH_SIZE:8}  # Batch size for answer evaluation
   

   Important: For first-time setup, use ddl-auto: create to create database tables. After successful table creation, change it to ddl-auto: update to prevent data loss on subsequent restarts.

Step 6: Start the Backend

1. Build and run the Spring Boot application

   Gradle (Unix/macOS)

   ./gradlew bootRun
   

   The backend service will start on http://localhost:8080

   First startup may take a few minutes as Gradle downloads dependencies and Spring Boot initializes database schemas.

2. Verify backend is running

   Check that the service is healthy:

   curl http://localhost:8080/api/resumes
   # Should return: {"code":200,"data":[],"message":"success"}
   

Step 7: Start the Frontend

1. Install dependencies

   Navigate to the frontend directory and install packages:

   pnpm

   cd frontend
   pnpm install
   
2. Start development server

   pnpm

   pnpm dev
   

   The frontend will start on http://localhost:5173

3. Access the application

   Open your browser and navigate to:

   InterviewGuide Application

   http://localhost:5173

   You should see the InterviewGuide homepage with options to upload resumes, start mock interviews, and manage your knowledge base.

What’s Next?

Resume Analysis

Upload and analyze resumes with AI-powered insights

Mock Interview

Practice interviews with intelligent follow-up questions

Knowledge Base

Build a RAG-powered knowledge base for intelligent Q&A

Configuration

Fine-tune your installation with advanced settings

Troubleshooting

Backend won’t start

Check PostgreSQL connection:

psql -h localhost -U postgres -d interview_guide

Check Redis connection:

redis-cli ping

Resume analysis stuck in “Processing” state

1. Verify Redis is running and accessible
2. Check backend logs for Redis Stream consumer errors
3. Ensure AI_BAILIAN_API_KEY is set correctly

Knowledge base vectorization fails

If you see errors related to vector_store table:

1. Ensure pgvector extension is enabled: CREATE EXTENSION IF NOT EXISTS vector;
2. Set spring.ai.vectorstore.pgvector.initialize-schema: true in application.yml
3. Check that the AI embedding model is accessible

PDF export shows garbled Chinese characters

The project includes the Zhuque Fangsong font for Chinese support. Verify the font file exists:

ls app/src/main/resources/fonts/ZhuqueFangsong-Regular.ttf

For more detailed troubleshooting, check the Common Issues section or review backend logs with ./gradlew bootRun --debug