Development

Docker Development Setup

Run all LAREX services using Docker Compose for development.

Docker Development Setup

This guide covers running all LAREX services using Docker Compose, including hot reload support.

Overview

Docker Compose provides a complete development environment with all services running in containers:

  • Frontend: Hot reload via volume mounts
  • Backend: Spring DevTools with volume mounts
  • PostgreSQL: Persistent data
  • Keycloak: Pre-configured realm
  • Traefik: Reverse proxy with automatic routing

Quick Start

Start All Services

# Start all services
task docker:up

# Build images before starting
task docker:up:build

Start Infrastructure Only

# Start only database, Keycloak, and Traefik
task docker:infra

This allows running frontend/backend locally while using containerized infrastructure.

View Logs

# All services
task docker:logs

# Specific service
task docker:logs:backend
task docker:logs:frontend

Stop Services

# Stop without removing data
task docker:down

# Stop and remove volumes (data loss!)
task docker:down:clean

Service Configuration

Development Services

The compose.yaml file defines development services:

services:
  postgres:
    image: postgres:17.5-alpine
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  keycloak:
    image: quay.io/keycloak/keycloak:26.3.3
    command: start-dev --import-realm
    ports:
      - "8090:8080"

  traefik:
    image: traefik:v3.6.7
    ports:
      - "80:80"
      - "8081:8080"

  app:
    build:
      context: backend
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
      - "5005:5005"
    volumes:
      - ./backend/src:/app/src:cached
    environment:
      SPRING_PROFILES_ACTIVE: dev

  frontend:
    build:
      context: frontend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    volumes:
      - ./frontend:/app
      - /app/node_modules

Hot Reload with Docker

Both frontend and backend support hot reload via volume mounts:

ServiceVolume MountHot Reload Behavior
Backend./backend/src:/app/srcSpring DevTools restart
Frontend./frontend:/appVite HMR
Gradle./backend:/appGradle cache sharing

Traefik Routing

Development routes are configured via labels:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.frontend.rule=Host(`larex.localhost`)"
  - "traefik.http.routers.api.rule=Host(`api.localhost`)"
  - "traefik.http.routers.keycloak.rule=Host(`keycloak.localhost`)"

Hosts File

Add to /etc/hosts:

127.0.0.1 larex.localhost
127.0.0.1 api.localhost
127.0.0.1 keycloak.localhost

Development Workflow with Docker

Full Docker Workflow

# Start all services
task docker:up

# View logs
task docker:logs

# Make code changes (auto-reload via volumes)

# Stop services
task docker:down

Hybrid Workflow (Recommended)

# Start infrastructure only
task docker:infra

# Terminal 1: Run backend locally
cd backend && ./gradlew bootRun

# Terminal 2: Run frontend locally
cd frontend && pnpm dev

# Access via http://larex.localhost

Benefits:

  • Better debugging experience
  • Faster hot reload
  • Local terminal output

Debugging in Docker

# Attach debugger to backend
# Configure IDE to connect to localhost:5005

# View backend logs
task docker:logs:backend

Service Health Checks

All services include health checks:

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U larex -d larexdb"]
  interval: 10s
  timeout: 5s
  retries: 5

Check service health:

task docker:ps

Data Persistence

Volumes

VolumePurposePersists on restart?
postgres_dataDatabase filesYes
gradle_cacheGradle dependenciesYes

Backing Up Data

# Backup PostgreSQL
docker compose exec postgres pg_dump -U larex larexdb > backup.sql

# Backup volumes
docker run --rm -v larex_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres.tar.gz -C /data .

Troubleshooting Docker

Containers Not Starting

# Check container status
task docker:ps

# View all logs
docker compose logs

# Check specific service
docker compose logs app

Volume Issues

# Remove all volumes and start fresh
task docker:down:clean
task docker:up

Network Issues

# Check Docker networks
docker network ls
docker network inspect larex_default

Port Conflicts

# Check what's using ports
lsof -i :80
lsof -i :443
lsof -i :5432

# Stop conflicting services
docker compose down

Next Steps

Local Development Setup

Set up and run LAREX services locally for development.

Command Reference

Complete reference for all Taskfile commands and development scripts.

Copyright © 2026