initial
This commit is contained in:
+470
@@ -0,0 +1,470 @@
|
||||
# Development Guide for MTG Search
|
||||
|
||||
## Local Development Environment Setup
|
||||
|
||||
### Prerequisites Installation
|
||||
|
||||
#### macOS
|
||||
```bash
|
||||
# Install Homebrew if not already installed
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
|
||||
# Install Java 21
|
||||
brew install --cask java
|
||||
|
||||
# Install Node.js
|
||||
brew install node@20
|
||||
|
||||
# Install PostgreSQL
|
||||
brew install postgresql
|
||||
|
||||
# Install Docker
|
||||
brew install --cask docker
|
||||
```
|
||||
|
||||
#### Ubuntu/Debian
|
||||
```bash
|
||||
# Install Java 21
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y openjdk-21-jdk
|
||||
|
||||
# Install Node.js
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
|
||||
# Install PostgreSQL
|
||||
sudo apt-get install -y postgresql postgresql-contrib
|
||||
|
||||
# Install Docker
|
||||
curl -fsSL https://get.docker.com | sudo sh
|
||||
sudo usermod -aG docker $USER
|
||||
```
|
||||
|
||||
#### Windows
|
||||
1. Install Java 21 from [Oracle](https://www.oracle.com/java/technologies/downloads/)
|
||||
2. Install Node.js from [nodejs.org](https://nodejs.org)
|
||||
3. Install PostgreSQL from [postgresql.org](https://www.postgresql.org/download/windows/)
|
||||
4. Install Docker Desktop from [docker.com](https://www.docker.com/products/docker-desktop)
|
||||
|
||||
### Quick Start with Startup Script
|
||||
|
||||
```bash
|
||||
# Make script executable
|
||||
chmod +x startup.sh
|
||||
|
||||
# Run the startup script
|
||||
./startup.sh
|
||||
```
|
||||
|
||||
### Manual Setup
|
||||
|
||||
#### Step 1: Start PostgreSQL
|
||||
|
||||
**Using Docker (Recommended):**
|
||||
```bash
|
||||
docker run --name mtgsearch-postgres \
|
||||
-e POSTGRES_DB=mtgsearch \
|
||||
-e POSTGRES_USER=postgres \
|
||||
-e POSTGRES_PASSWORD=postgres \
|
||||
-p 5432:5432 \
|
||||
-d postgres:16-alpine
|
||||
```
|
||||
|
||||
**Using Local PostgreSQL:**
|
||||
```bash
|
||||
# macOS
|
||||
brew services start postgresql
|
||||
|
||||
# Linux
|
||||
sudo systemctl start postgresql
|
||||
|
||||
# Windows
|
||||
# Start from Services or GUI
|
||||
```
|
||||
|
||||
#### Step 2: Verify Database Connection
|
||||
|
||||
```bash
|
||||
psql -U postgres -h localhost -d mtgsearch -c "SELECT 1;"
|
||||
```
|
||||
|
||||
#### Step 3: Build and Run Backend
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Build with Gradle
|
||||
../gradlew build
|
||||
|
||||
# Run the application
|
||||
../gradlew bootRun
|
||||
|
||||
# The backend will start on http://localhost:8080
|
||||
```
|
||||
|
||||
#### Step 4: Set Up and Run Frontend
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Start development server
|
||||
npm run dev
|
||||
|
||||
# The frontend will start on http://localhost:5173
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Making Changes
|
||||
|
||||
#### Backend Changes
|
||||
1. Edit Java files in `backend/src/main/java`
|
||||
2. Spring Boot DevTools will auto-reload
|
||||
3. Check logs: `tail -f logs/mtg-search.log`
|
||||
|
||||
#### Frontend Changes
|
||||
1. Edit Vue files in `frontend/src`
|
||||
2. Vite will hot-reload automatically
|
||||
3. Check browser console for errors
|
||||
|
||||
### Testing
|
||||
|
||||
#### Backend Tests
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Run all tests
|
||||
../gradlew test
|
||||
|
||||
# Run specific test class
|
||||
../gradlew test --tests AuthServiceTest
|
||||
|
||||
# Run with coverage
|
||||
../gradlew test jacocoTestReport
|
||||
```
|
||||
|
||||
#### Frontend Tests
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Run tests
|
||||
npm run test
|
||||
|
||||
# Run with coverage
|
||||
npm run test -- --coverage
|
||||
|
||||
# Watch mode
|
||||
npm run test -- --watch
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
#### Backend
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Run checks (spotless, checkstyle, etc.)
|
||||
../gradlew check
|
||||
|
||||
# Format code
|
||||
../gradlew spotlessApply
|
||||
```
|
||||
|
||||
#### Frontend
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Run linter
|
||||
npm run lint
|
||||
|
||||
# Fix linting issues
|
||||
npm run lint --fix
|
||||
```
|
||||
|
||||
## Database Management
|
||||
|
||||
### Running Flyway Migrations
|
||||
|
||||
Migrations run automatically when the application starts. To manage migrations manually:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Show migration status
|
||||
../gradlew flywayInfo
|
||||
|
||||
# Validate migrations
|
||||
../gradlew flywayValidate
|
||||
|
||||
# Repair (use with caution)
|
||||
../gradlew flywayRepair
|
||||
|
||||
# Clean schema (WARNING: deletes all data)
|
||||
../gradlew flywayClean
|
||||
```
|
||||
|
||||
### Creating New Migration
|
||||
|
||||
1. Create file: `backend/src/main/resources/db/migration/V{NUMBER}__Description.sql`
|
||||
|
||||
Example:
|
||||
```sql
|
||||
-- V2__Add_search_history_table.sql
|
||||
CREATE TABLE IF NOT EXISTS search_history (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
user_id BIGINT NOT NULL REFERENCES users(id),
|
||||
search_query VARCHAR(255) NOT NULL,
|
||||
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
|
||||
);
|
||||
|
||||
CREATE INDEX idx_search_history_user_id ON search_history(user_id);
|
||||
```
|
||||
|
||||
## API Endpoints Testing
|
||||
|
||||
### Using curl
|
||||
|
||||
```bash
|
||||
# Register a new user
|
||||
curl -X POST http://localhost:8080/api/v1/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "testuser",
|
||||
"email": "test@example.com",
|
||||
"password": "SecurePassword123!"
|
||||
}'
|
||||
|
||||
# Login
|
||||
curl -X POST http://localhost:8080/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "testuser",
|
||||
"password": "SecurePassword123!"
|
||||
}'
|
||||
|
||||
# Use token in requests
|
||||
TOKEN=<your-jwt-token>
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
http://localhost:8080/api/v1/protected-endpoint
|
||||
```
|
||||
|
||||
### Using Swagger UI
|
||||
|
||||
Navigate to: http://localhost:8080/swagger-ui.html
|
||||
|
||||
## Debugging
|
||||
|
||||
### Backend Debugging
|
||||
|
||||
#### In IDE (IntelliJ IDEA)
|
||||
1. Set breakpoints in your code
|
||||
2. Run → Debug 'MtgSearchApplication'
|
||||
3. Step through code
|
||||
|
||||
#### Remote Debugging
|
||||
```bash
|
||||
cd backend
|
||||
../gradlew bootRun --args='--debug'
|
||||
|
||||
# Then connect remote debugger on port 5005
|
||||
```
|
||||
|
||||
### Frontend Debugging
|
||||
|
||||
1. Open browser DevTools (F12 or Cmd+Option+I)
|
||||
2. Check Console, Network, and Application tabs
|
||||
3. Use Vue DevTools browser extension
|
||||
|
||||
### Logs
|
||||
|
||||
```bash
|
||||
# Backend logs
|
||||
tail -f logs/mtg-search.log
|
||||
|
||||
# Backend errors
|
||||
tail -f logs/mtg-search-error.log
|
||||
|
||||
# Frontend browser console
|
||||
# Open DevTools → Console tab
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Create `.env` file in project root:
|
||||
|
||||
```env
|
||||
# Database
|
||||
DB_URL=jdbc:postgresql://localhost:5432/mtgsearch
|
||||
DB_USER=postgres
|
||||
DB_PASSWORD=postgres
|
||||
|
||||
# JWT
|
||||
JWT_SECRET=development-secret-key
|
||||
JWT_EXPIRATION=86400
|
||||
|
||||
# Application
|
||||
SPRING_PROFILE=dev
|
||||
|
||||
# Frontend
|
||||
VITE_API_URL=http://localhost:8080
|
||||
```
|
||||
|
||||
## IDE Configuration
|
||||
|
||||
### IntelliJ IDEA
|
||||
1. Open project root folder
|
||||
2. File → Project Structure → Modules
|
||||
3. Select backend module
|
||||
4. Set Java 21 as SDK
|
||||
5. Install Spring Boot plugin
|
||||
6. Install Lombok plugin
|
||||
|
||||
### VS Code
|
||||
1. Install extensions:
|
||||
- Extension Pack for Java
|
||||
- Spring Boot Extension Pack
|
||||
- Vue 3 Extension
|
||||
- TypeScript Vue Plugin
|
||||
2. Configure Java home in settings
|
||||
3. Install Node modules
|
||||
|
||||
## Useful Gradle Commands
|
||||
|
||||
```bash
|
||||
# Build tasks
|
||||
./gradlew build # Full build
|
||||
./gradlew clean build # Clean and build
|
||||
./gradlew build -x test # Build without tests
|
||||
|
||||
# Test tasks
|
||||
./gradlew test # Run tests
|
||||
./gradlew test --watch # Watch mode
|
||||
|
||||
# Development tasks
|
||||
./gradlew bootRun # Run application
|
||||
./gradlew bootRun --debug # Debug mode
|
||||
|
||||
# Code generation
|
||||
./gradlew openApiGenerate # Generate from OpenAPI spec
|
||||
./gradlew generateJooqCode # Generate jOOQ entities
|
||||
|
||||
# Database tasks
|
||||
./gradlew flywayInfo # Show migration status
|
||||
./gradlew flywayMigrate # Run migrations
|
||||
```
|
||||
|
||||
## Useful npm Commands
|
||||
|
||||
```bash
|
||||
# Development
|
||||
npm run dev # Start dev server
|
||||
npm run build # Build for production
|
||||
npm run preview # Preview production build
|
||||
|
||||
# Testing
|
||||
npm run test # Run tests
|
||||
npm run test:ui # Run tests with UI
|
||||
npm run test -- --watch # Watch mode
|
||||
|
||||
# Quality
|
||||
npm run lint # Run linter
|
||||
npm run type-check # Check TypeScript types
|
||||
```
|
||||
|
||||
## Troubleshooting Common Issues
|
||||
|
||||
### "Address already in use" port 8080
|
||||
```bash
|
||||
# Find process using port 8080
|
||||
lsof -i :8080
|
||||
|
||||
# Kill the process
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
### "Address already in use" port 5173
|
||||
```bash
|
||||
# Find process using port 5173
|
||||
lsof -i :5173
|
||||
|
||||
# Kill the process
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
### PostgreSQL connection refused
|
||||
```bash
|
||||
# Check if PostgreSQL is running
|
||||
psql --version
|
||||
|
||||
# Try to connect
|
||||
psql -U postgres -h localhost
|
||||
|
||||
# If using Docker, check container
|
||||
docker ps | grep postgres
|
||||
docker logs mtgsearch-postgres
|
||||
```
|
||||
|
||||
### Gradle build fails
|
||||
```bash
|
||||
# Clear gradle cache
|
||||
rm -rf ~/.gradle/caches
|
||||
|
||||
# Clean and rebuild
|
||||
./gradlew clean build --refresh-dependencies
|
||||
```
|
||||
|
||||
### Frontend build fails
|
||||
```bash
|
||||
# Clear node_modules
|
||||
rm -rf frontend/node_modules package-lock.json
|
||||
|
||||
# Reinstall dependencies
|
||||
cd frontend && npm install
|
||||
```
|
||||
|
||||
### Flyway migration fails
|
||||
```bash
|
||||
# Check migration status
|
||||
cd backend && ../gradlew flywayInfo
|
||||
|
||||
# Validate migrations
|
||||
../gradlew flywayValidate
|
||||
|
||||
# Start fresh (DELETES ALL DATA)
|
||||
../gradlew flywayClean
|
||||
../gradlew flywayMigrate
|
||||
```
|
||||
|
||||
## Performance Profiling
|
||||
|
||||
### Backend
|
||||
```bash
|
||||
# Generate JFR recording
|
||||
cd backend
|
||||
../gradlew bootRun --jvmArgs="-XX:StartFlightRecording=filename=recording.jfr"
|
||||
|
||||
# Analyze with Java Flight Recorder
|
||||
jmc recording.jfr
|
||||
```
|
||||
|
||||
### Frontend
|
||||
```bash
|
||||
# Build with source maps
|
||||
cd frontend
|
||||
npm run build -- --sourcemap
|
||||
|
||||
# Use Chrome DevTools Performance tab
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Spring Boot Documentation](https://spring.io/projects/spring-boot)
|
||||
- [Vue 3 Documentation](https://vuejs.org)
|
||||
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
|
||||
- [Gradle Documentation](https://gradle.org/guides/)
|
||||
- [Docker Documentation](https://docs.docker.com/)
|
||||
- [GitLab CI/CD Documentation](https://docs.gitlab.com/ee/ci/)
|
||||
Reference in New Issue
Block a user