Development
Local Development Setup
Set up and run LAREX services locally for development.
Local Development Setup
This guide covers running LAREX services locally without Docker for a better development experience with hot reload.
Prerequisites
Ensure infrastructure services are running:
# Start infrastructure (PostgreSQL, Keycloak, Traefik)
task docker:infra
# Verify services
task status
Backend Development
Running the Backend
cd backend
# Start development server with hot reload
./gradlew bootRun
# Or using Taskfile
task dev
The backend will start on http://localhost:8080.
Debug Mode
# Start with debug enabled
./gradlew bootRun -Pdebug
# Or use the Taskfile shortcut
task dev:debug
This enables:
- JVM debug port on 5005
- Spring DevTools hot reload
- Live class reloading
Available Commands
cd backend
# Build without tests
./gradlew build -x test
# Build JAR file
./gradlew bootJar
# Run tests
./gradlew test
# Run tests with verbose output
./gradlew test --info
# Clean build artifacts
./gradlew clean
# Check dependencies
./gradlew dependencies
# Format code
./gradlew spotlessApply
Frontend Development
Running the Frontend
cd frontend
# Start development server
pnpm dev
# Or using Taskfile from root
task frontend:dev
The frontend will start on http://localhost:3000.
Available Commands
cd frontend
# Install dependencies
pnpm install
# Start development server
pnpm dev
# Build for production
pnpm build
# Preview production build
pnpm preview
# Linting
pnpm lint
# Auto-fix linting issues
pnpm lint --fix
# Type checking
pnpm typecheck
Development Ports
| Service | Port | URL | Description |
|---|---|---|---|
| Frontend | 3000 | http://localhost:3000 | Nuxt.js development server |
| Backend | 8080 | http://localhost:8080 | Spring Boot development server |
| Backend Debug | 5005 | - | JVM debug port |
| PostgreSQL | 5432 | localhost:5432 | Database |
| Keycloak | 8090 | http://localhost:8090 | Identity provider |
Hot Reload Configuration
Backend Hot Reload
Spring Boot DevTools is enabled by default:
# In compose.yaml
environment:
SPRING_DEVTOOLS_RESTART_ENABLED: true
SPRING_DEVTOOLS_LIVERELOAD_ENABLED: true
Changes to src/main/java trigger automatic restart.
Frontend Hot Reload
Nuxt.js provides HMR out of the box. Changes to:
app/components/- Auto-imported componentsapp/pages/- Routesapp/composables/- Composablesapp/stores/- Pinia stores
Trigger instant browser updates.
Development Workflow
Typical Development Session
# Terminal 1: Infrastructure (once)
task docker:infra
# Terminal 2: Backend
cd backend && ./gradlew bootRun
# Terminal 3: Frontend
cd frontend && pnpm dev
Making Changes
- Backend changes: Automatically reloaded via DevTools
- Frontend changes: Instant HMR via Vite
- Database changes: Hibernate auto-updates schema (dev only)
Testing Changes
# Backend tests
cd backend && ./gradlew test
# Frontend lint/typecheck
cd frontend && pnpm lint && pnpm typecheck
# All tests
task test
Troubleshooting Local Development
Port Already in Use
# Find process using port
lsof -i :8080
lsof -i :3000
# Kill process
kill -9 <PID>
Database Connection Issues
# Verify PostgreSQL is running
docker ps | grep postgres
# Check logs
docker compose logs postgres
Keycloak Not Ready
# Wait for Keycloak health
curl http://localhost:8090/health/ready
# Restart Keycloak
docker compose restart keycloak
Frontend Build Errors
# Clear node_modules and reinstall
cd frontend
rm -rf node_modules pnpm-lock.yaml
pnpm install
Next Steps
- Docker Development - Use Docker for all services
- Command Reference - Complete command list