Quick Start Guide

This guide will help you get the entire StreamLine Logistics system running on your local machine using Docker Compose.

Prerequisites

Before you begin, ensure you have the following installed:

Docker (version 20.10 or higher)
Docker Compose (version 2.0 or higher)
Java 17 (for local development)
Maven 3.8+ (for building from source)
Git (to clone the repository)

The Docker Compose setup will automatically handle all database and service dependencies. You don’t need to install PostgreSQL, MySQL, or MongoDB separately.

Getting Started

Clone the Repository

Clone the StreamLine Logistics repository to your local machine:

git clone <repository-url>
cd StreamLine-Logistics

Build the Services

Build all microservices using Maven. This will compile the code and create Docker images:

mvn clean package

The build process uses Spring Boot 4.0.2 with Java 17 and includes Lombok and MapStruct annotation processors.

This command will:

Compile all microservices
Run unit tests
Generate Jacoco coverage reports
Package each service as an executable JAR

Start the System

Launch all services and databases using Docker Compose:

docker-compose up -d

This single command will start:

3 databases: PostgreSQL (orders), MySQL (inventory), MongoDB (tracking)
Eureka Server: Service discovery
Order Service: Order management API
Inventory Service: Stock management API
Tracking Service: Shipment tracking API

The -d flag runs containers in detached mode. Omit it if you want to see logs in your terminal.

Verify Services are Running

Check that all containers are healthy:

docker-compose ps

You should see all services in the “Up” state:

NAME                IMAGE                      STATUS
eureka-server       eureka-service:latest      Up
order-service       order-service:latest       Up
inventory-service   inventory-service:latest   Up
tracking-service    tracking-service:latest    Up
order_db            postgres:15                Up
inventory_db        mysql:8                    Up
tracking_db         mongo:latest               Up

Access the Eureka Dashboard

Open your browser and navigate to the Eureka Server dashboard:

http://localhost:8761

You should see all three microservices registered:

MSVC-ORDER
MSVC-INVENTORY
MSVC-TRACKING

If services aren’t showing up, they may still be starting. Wait 30-60 seconds and refresh the page.

Test the APIs

Create your first product in the inventory:

curl -X POST http://localhost:9090/api/v1/inventory \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "LAPTOP-001",
    "name": "Dell XPS 15",
    "description": "High-performance laptop",
    "price": 1299.99,
    "stock": 50
  }'

Retrieve all products:

curl http://localhost:9090/api/v1/inventory

API documentation is available via Swagger UI at http://localhost:9090/swagger-ui.html (when gateway is configured).

Service Ports Reference

All services are accessible on the following ports:

Service	Port	URL	Status
Eureka Server	8761	http://localhost:8761	✅ Active
Order Service	8090	http://localhost:8090	✅ Active
Inventory Service	9090	http://localhost:9090	✅ Active
Tracking Service	8091	http://localhost:8091	✅ Active
PostgreSQL (Orders)	5432	localhost:5432	✅ Active
MySQL (Inventory)	3306	localhost:3306	✅ Active
MongoDB (Tracking)	27017	localhost:27017	✅ Active
API Gateway	8080	http://localhost:8080	⚠️ Not in docker-compose
Config Server	8888	http://localhost:8888	⚠️ Not in docker-compose

The API Gateway and Config Server modules exist in the codebase but are not yet included in the docker-compose.yml deployment. Services can be accessed directly on their respective ports.

Database Connections

If you need to connect directly to the databases for debugging:

psql -h localhost -p 5432 -U postgres -d orderdb
Password: password

These credentials are for development only. Never use default credentials in production environments.

Example API Workflows

Managing Inventory

Create a Product

curl -X POST http://localhost:9090/api/v1/inventory \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "TSHIRT-BLUE-L",
    "name": "Blue T-Shirt Large",
    "description": "Cotton blue t-shirt, size L",
    "price": 29.99,
    "stock": 100
  }'

Get Product Details

# Replace {id} with the product ID from the previous response
curl http://localhost:9090/api/v1/inventory/{id}

Reserve Stock

curl -X POST http://localhost:9090/api/v1/inventory/{id}/reserveStock \
  -H "Content-Type: application/json" \
  -d '{"amount": 5}'

Consume Stock (Ship Order)

curl -X POST http://localhost:9090/api/v1/inventory/{id}/consumeStock \
  -H "Content-Type: application/json" \
  -d '{"amount": 5}'

Viewing Logs

To view logs for a specific service:

# View logs for inventory service
docker-compose logs -f inventory-service

# View logs for all services
docker-compose logs -f

# View last 100 lines
docker-compose logs --tail=100 inventory-service

Stopping the System

To stop all services while preserving data:

docker-compose stop

To stop and remove all containers (data in volumes is preserved):

docker-compose down

To completely remove all data including database volumes, use:

docker-compose down -v

This will delete all orders, products, and tracking information.

Troubleshooting

Services not registering with Eureka

Problem: Microservices don’t appear in the Eureka dashboard.Solution:

Ensure Eureka Server is running: docker-compose ps eureka-server
Check service logs: docker-compose logs inventory-service
Verify network connectivity: All services must be on the microservices-network
Wait 30-60 seconds - registration may take time on slower systems

Database connection errors

Problem: Services fail to connect to databases.Solution:

Verify databases are running: docker-compose ps order_db inventory_db tracking_db
Check database logs: docker-compose logs order_db
Ensure databases are ready before services start (add healthchecks to docker-compose.yml)
Verify connection strings in application.yml files match container names

Port conflicts

Problem: Bind for 0.0.0.0:8090 failed: port is already allocatedSolution:

Check what’s using the port: lsof -i :8090 (macOS/Linux) or netstat -ano | findstr :8090 (Windows)
Stop the conflicting process or change the port mapping in docker-compose.yml
Example: Change "8090:8090" to "8095:8090" to use port 8095 externally

Out of memory errors

Problem: Services crash with OutOfMemoryError.Solution:

Increase Docker memory allocation in Docker Desktop settings (minimum 4GB recommended)
Add JVM memory limits in Dockerfiles: JAVA_OPTS="-Xmx512m -Xms256m"
Stop unused services to free resources

Next Steps

Now that your system is running:

Architecture

Learn about the system architecture and data models

API Reference

Explore the complete API documentation

Getting Started

Setup & Deployment

Microservices

Infrastructure

Operations

Quick Start

Quick Start Guide

Prerequisites

Getting Started

Service Ports Reference

Database Connections

Example API Workflows

Managing Inventory

Viewing Logs

Stopping the System

Troubleshooting

Next Steps

Architecture

API Reference

Build docs developers (and LLMs) love

Getting Started

Setup & Deployment

Microservices

Infrastructure

Operations

​Quick Start Guide

​Prerequisites

​Getting Started

​Service Ports Reference

​Database Connections

​Example API Workflows

​Managing Inventory

​Viewing Logs

​Stopping the System

​Troubleshooting

​Next Steps

Architecture

API Reference

Build docs developers (and LLMs) love

Quick Start Guide

Prerequisites

Getting Started

Service Ports Reference

Database Connections

Example API Workflows

Managing Inventory

Viewing Logs

Stopping the System

Troubleshooting

Next Steps