Local Development Setup

Overview

This guide walks you through setting up the Product Distribution Dashboard for local development, allowing you to run the backend and frontend separately with hot reload capabilities for rapid development.

Prerequisites

Ensure you have the following installed on your development machine:

Java Development Kit (JDK)

Version Required: Java 17Verify installation:

java -version

Expected output: openjdk version "17.x.x"Download from:

Apache Maven

Version Required: Maven 3.9+Verify installation:

mvn -version

Download from: Apache Maven

Node.js

Version Required: Node.js 20.xVerify installation:

node -v
npm -v

Download from: Node.js Official Site

Use nvm for managing multiple Node.js versions.

PostgreSQL

Version Required: PostgreSQL 16Install PostgreSQL locally or use Docker:

docker run -d \
  --name postgres-dev \
  -e POSTGRES_DB=product_distribution_db \
  -e POSTGRES_USER=product_distribution \
  -e POSTGRES_PASSWORD=product_distribution \
  -p 5432:5432 \
  postgres:16-alpine

Git

Verify installation:

git --version

Database Setup

Create Database

If you installed PostgreSQL locally, create the database:

psql -U postgres

Then in the PostgreSQL prompt:

CREATE DATABASE product_distribution_db;
CREATE USER product_distribution WITH PASSWORD 'product_distribution';
GRANT ALL PRIVILEGES ON DATABASE product_distribution_db TO product_distribution;

Verify Connection

Test the database connection:

psql -h localhost -p 5432 -U product_distribution -d product_distribution_db

Password: product_distribution

If using Docker for PostgreSQL (recommended), the database is automatically created with the correct credentials.

Backend Setup

Navigate to Backend Directory

cd backend

Configure Environment

The backend uses Spring profiles. For local development, the dev profile is active by default.Create a .env file in the backend directory (optional) or export environment variables:

export SPRING_PROFILES_ACTIVE=dev
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/product_distribution_db
export SPRING_DATASOURCE_USERNAME=product_distribution
export SPRING_DATASOURCE_PASSWORD=product_distribution
export APP_FRONTEND_URL=http://localhost:4200

These are the default values in application-dev.properties. Only set environment variables if you need to override defaults.

Install Dependencies

Download all Maven dependencies:

mvn dependency:go-offline

This may take a few minutes on first run.

Run the Backend

Start the Spring Boot application:

mvn spring-boot:run

The backend will start on port 8080 by default.

Verify Backend is Running

Check the health endpoint:

curl http://localhost:8080/actuator/health

Expected response:

{"status":"UP"}

Backend Hot Reload

The backend includes Spring Boot DevTools for automatic restart on code changes:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-devtools</artifactId>
  <scope>runtime</scope>
  <optional>true</optional>
</dependency>

DevTools automatically restarts the application when classes change. Build the project in your IDE or run mvn compile to trigger a restart.

Frontend Setup

Navigate to Frontend Directory

cd frontend

Install Dependencies

Install all npm packages:

npm ci

Use npm ci for clean installs (recommended for development) or npm install to update packages.

Configure API Endpoint

The frontend is configured to connect to the backend at http://localhost:8080 by default.If you need to change this, update the API base URL in your environment configuration files.

Run the Frontend

Start the Angular development server:

npm start

The frontend will start on port 4200 by default.

Access the Application

Open your browser and navigate to:http://localhost:4200The application should load with hot reload enabled.

Frontend Hot Reload

Angular’s development server includes automatic hot reload:

Changes to TypeScript files trigger recompilation
Browser automatically refreshes on successful build
Live reload for HTML and SCSS changes

Keep the terminal running to maintain the development server. Press Ctrl+C to stop.

Development Workflow

Running Both Services Simultaneously

For full-stack development, you’ll need two terminal windows:

cd backend
mvn spring-boot:run

Building for Production

Build Backend

cd backend
mvn clean package -DskipTests

Output: target/backend-0.0.1-SNAPSHOT.jar

Build Frontend

cd frontend
npm run build

Output: dist/frontend/browser/

Production builds are optimized with minification and tree-shaking.

Running Tests

cd backend
mvn test

Code Formatting

The frontend includes Prettier for code formatting:

cd frontend
npm run format

Configuration Files

Backend Configuration

The backend uses Spring profiles for different environments:

File	Profile	Purpose
`application.properties`	Default	Base configuration
`application-dev.properties`	dev	Local development settings
`application-prod.properties`	prod	Production settings
`application-test.properties`	test	Test configuration

Key Configuration Properties (Dev Profile):

spring.datasource.url=${SPRING_DATASOURCE_URL}
spring.datasource.username=${SPRING_DATASOURCE_USERNAME}
spring.datasource.password=${SPRING_DATASOURCE_PASSWORD}
app.frontend.url=${APP_FRONTEND_URL}
scheduler.distribution.cron=3 * * * * *

Frontend Configuration

Package.json Scripts:

{
  "start": "ng serve",
  "build": "ng build",
  "watch": "ng build --watch --configuration development",
  "test": "ng test",
  "lint": "ng lint",
  "format": "prettier --write \"src/**/*.{ts,html,scss,json}\""
}

Environment Variables Reference

Backend Environment Variables

Variable	Default	Description
`SPRING_PROFILES_ACTIVE`	dev	Active Spring profile
`SPRING_DATASOURCE_URL`	Required	PostgreSQL JDBC URL
`SPRING_DATASOURCE_USERNAME`	Required	Database username
`SPRING_DATASOURCE_PASSWORD`	Required	Database password
`APP_FRONTEND_URL`	Required	Frontend URL for CORS
`PORT`	8080	Server port
`DATA_PRODUCTS_URL`	GitHub URL	Products data source
`DATA_STORES_URL`	GitHub URL	Stores data source
`DATA_WAREHOUSES_URL`	GitHub URL	Warehouses data source

Development Values

SPRING_PROFILES_ACTIVE=dev
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/product_distribution_db
SPRING_DATASOURCE_USERNAME=product_distribution
SPRING_DATASOURCE_PASSWORD=product_distribution
APP_FRONTEND_URL=http://localhost:4200

Troubleshooting

Backend Won’t Start

Issue: Port 8080 already in use Solution: Change the port in application.properties or set the PORT environment variable:

export PORT=8081
mvn spring-boot:run

Issue: Database connection failed Solution:

Verify PostgreSQL is running:

docker ps  # if using Docker
# or
pg_isready -h localhost -p 5432

Check database credentials in environment variables

Ensure database exists:

psql -U postgres -l | grep product_distribution_db

Frontend Won’t Start

Issue: node_modules errors Solution: Delete and reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Issue: Port 4200 already in use Solution: Use a different port:

ng serve --port 4201

Hot Reload Not Working

Backend:

Ensure DevTools is in the classpath
Check if your IDE automatically compiles on save
Manually trigger compilation with mvn compile

Frontend:

Restart the development server
Clear browser cache
Check browser console for errors

Maven Build Errors

Issue: Dependencies won’t download Solution:

mvn clean install -U

The -U flag forces update of snapshots and releases.

Issue: MapStruct annotation processing errors Solution: Ensure Lombok and MapStruct are configured correctly in pom.xml:

<dependency>
  <groupId>org.mapstruct</groupId>
  <artifactId>mapstruct</artifactId>
  <version>1.6.3</version>
</dependency>
<dependency>
  <groupId>org.projectlombok</groupId>
  <artifactId>lombok</artifactId>
  <version>1.18.42</version>
</dependency>

IDE Configuration

IntelliJ IDEA

Enable Annotation Processing

Settings → Build, Execution, Deployment → Compiler → Annotation ProcessorsCheck: “Enable annotation processing”

Install Lombok Plugin

Settings → Plugins → Search “Lombok” → Install

Import Maven Project

File → Open → Select backend/pom.xml

VS Code

Recommended Extensions:

Spring Boot Extension Pack
Java Extension Pack
Angular Language Service
Prettier - Code formatter
ESLint

Get Started

Installation

Core Features

Configuration

Overview

Prerequisites

Database Setup

Backend Setup

Backend Hot Reload

Frontend Setup

Frontend Hot Reload

Development Workflow

Running Both Services Simultaneously

Building for Production

Running Tests

Code Formatting

Configuration Files

Backend Configuration

Frontend Configuration

Environment Variables Reference

Backend Environment Variables

Development Values

Troubleshooting

Backend Won’t Start

Frontend Won’t Start

Hot Reload Not Working

Maven Build Errors

IDE Configuration

IntelliJ IDEA

VS Code

Next Steps

Docker Setup

Deployment

Build docs developers (and LLMs) love

Get Started

Installation

Core Features

Configuration

​Overview

​Prerequisites

​Database Setup

​Backend Setup

​Backend Hot Reload

​Frontend Setup

​Frontend Hot Reload

​Development Workflow

​Running Both Services Simultaneously

​Building for Production

​Running Tests

​Code Formatting

​Configuration Files

​Backend Configuration

​Frontend Configuration

​Environment Variables Reference

​Backend Environment Variables

​Development Values

​Troubleshooting

​Backend Won’t Start

​Frontend Won’t Start

​Hot Reload Not Working

​Maven Build Errors

​IDE Configuration

​IntelliJ IDEA

​VS Code

​Next Steps

Docker Setup

Deployment

Build docs developers (and LLMs) love

Overview

Prerequisites

Database Setup

Backend Setup

Backend Hot Reload

Frontend Setup

Frontend Hot Reload

Development Workflow

Running Both Services Simultaneously

Building for Production

Running Tests

Code Formatting

Configuration Files

Backend Configuration

Frontend Configuration

Environment Variables Reference

Backend Environment Variables

Development Values

Troubleshooting

Backend Won’t Start

Frontend Won’t Start

Hot Reload Not Working

Maven Build Errors

IDE Configuration

IntelliJ IDEA

VS Code

Next Steps