Skip to main content

​
Overview

The Product Distribution Dashboard can be quickly deployed using Docker Compose, which orchestrates all required services including the backend, frontend, PostgreSQL database, and pgAdmin.

​
Prerequisites

Before starting, ensure you have the following installed:
1

Docker

Install Docker Desktop or Docker Engine (version 20.10 or higher)
2

Docker Compose

Docker Compose is included with Docker Desktop. For standalone installations, install Docker Compose v2.0 or higher.
3

System Resources

Ensure your system has at least:
  • 4 GB RAM available
  • 10 GB disk space
  • Ports 4200, 5050, 5432, and 8080 available

​
Docker Compose Configuration

The application uses a multi-service Docker Compose setup with the following architecture:

​
Services Overview

Image: postgres:16-alpineContainer Name: product-distribution-postgresPort: 5432:5432The PostgreSQL database stores all product distribution data including products, stores, warehouses, and distribution records.Environment Variables:
  • POSTGRES_DB: product_distribution_db
  • POSTGRES_USER: product_distribution
  • POSTGRES_PASSWORD: product_distribution
Health Check: Runs every 10 seconds to ensure database readiness before dependent services start.
Build Context: Root directory with backend/DockerfileContainer Name: product-distribution-backendPort: 8080:8080Spring Boot backend built with Java 17 and Maven. Includes health checks via Spring Boot Actuator.Environment Variables:
  • SPRING_PROFILES_ACTIVE: dev
  • SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/product_distribution_db
  • SPRING_DATASOURCE_USERNAME: product_distribution
  • SPRING_DATASOURCE_PASSWORD: product_distribution
  • APP_FRONTEND_URL: http://localhost:4200
Dependencies: Waits for PostgreSQL health check to pass before starting.
Build Context: frontend/ directoryContainer Name: product-distribution-frontendPort: 4200:4200Angular 18 application with Node.js 20. Runs in development mode with hot reload enabled.Dependencies: Starts after backend service.
Image: dpage/pgadmin4Container Name: pgadminPort: 5050:80Web-based PostgreSQL administration tool for database management.Environment Variables:Dependencies: Starts after PostgreSQL is running.

​
Installation Steps

1

Clone the Repository

git clone <repository-url>
cd product-distribution
2

Start All Services

Run Docker Compose to build and start all services:
docker-compose up --build
The --build flag ensures images are rebuilt if there are any code changes. For subsequent runs without code changes, you can omit this flag.
3

Wait for Services to Start

Monitor the logs to ensure all services start successfully:
  • PostgreSQL health check passes
  • Backend connects to database and starts on port 8080
  • Frontend compiles and serves on port 4200
You should see output similar to:
product-distribution-postgres    | database system is ready to accept connections
product-distribution-backend     | Started BackendApplication in X seconds
product-distribution-frontend    | ** Angular Live Development Server is listening
4

Verify Installation

Access the services to confirm they’re running:

​
Access Points

Once all services are running, you can access:
ServiceURLDescription
Frontend Dashboardhttp://localhost:4200Main application interface
Backend APIhttp://localhost:8080REST API endpoints
Health Checkhttp://localhost:8080/actuator/healthBackend health status
pgAdminhttp://localhost:5050Database management interface
PostgreSQLlocalhost:5432Direct database connection

​
pgAdmin Configuration

To connect to the PostgreSQL database from pgAdmin:
1

Login to pgAdmin

2

Add New Server

Right-click “Servers” → “Register” → “Server”
3

Configure Connection

General Tab:
  • Name: Product Distribution
Connection Tab:
  • Host: postgres
  • Port: 5432
  • Database: product_distribution_db
  • Username: product_distribution
  • Password: product_distribution

​
Managing Services

​
Start Services in Background

docker-compose up -d

​
Stop Services

docker-compose down
This command stops and removes containers but preserves the database volume.

​
Stop Services and Remove Volumes

docker-compose down -v
This will delete all database data. Use only when you want a complete reset.

​
View Logs

docker-compose logs -f

​
Restart a Service

docker-compose restart backend

​
Rebuild a Service

docker-compose up --build backend

​
Troubleshooting

​
Port Already in Use

Error: Bind for 0.0.0.0:8080 failed: port is already allocated Solution: Check which process is using the port and stop it: 
lsof -i :8080
kill -9 <PID>
Alternatively, modify the port mapping in docker-compose.yml: 
ports:
  - "8081:8080"  # Use port 8081 instead

​
Backend Cannot Connect to Database

Symptoms: Backend logs show connection errors to PostgreSQL Solution:
  1. Check if PostgreSQL container is healthy: 
    docker-compose ps
  2. Verify database logs: 
    docker-compose logs postgres
  3. Ensure the backend waits for database health check: 
    depends_on:
  postgres:
    condition: service_healthy

​
Container Keeps Restarting

Solution:
  1. Check container logs: 
    docker-compose logs <service-name>
  2. Inspect container status: 
    docker ps -a
  3. Common causes:
    • Missing environment variables
    • Port conflicts
    • Build errors
    • Insufficient resources

​
Database Connection Pool Exhausted

Symptoms: Backend logs show “Connection pool exhausted” errors Solution: Increase the connection pool size by setting environment variables: 
environment:
  SPRING_DATASOURCE_HIKARI_MAXIMUM_POOL_SIZE: 20

​
Out of Memory Errors

Solution: Increase Docker memory allocation:
  • Docker Desktop: Settings → Resources → Memory → Increase to 4+ GB
  • Linux: Adjust Docker daemon settings

​
Clean Build Issues

Solution: Remove all containers, images, and volumes for a fresh start: 
docker-compose down -v
docker system prune -a
docker-compose up --build
This removes all Docker resources. Use with caution.

​
Volume Management

The PostgreSQL data is persisted in a named volume: 
volumes:
  postgres_data:

​
Backup Database Volume

docker run --rm -v product-distribution_postgres_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/postgres-backup.tar.gz -C /data .

​
Restore Database Volume

docker run --rm -v product-distribution_postgres_data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/postgres-backup.tar.gz -C /data

​
Next Steps

Local Development

Set up the project for local development without Docker

Deployment

Deploy the application to production environments

Build docs developers (and LLMs) love

Get started for freeTalk to us