Skip to main content
This guide covers setting up your development environment to work with the Ecommerce Order Service.

​
Prerequisites

Before you begin, ensure you have the following installed:

Java 8+

JDK 8 or higher required

Gradle 5.6

Build automation tool (wrapper included)

Docker

For running MySQL, RabbitMQ, and Zipkin

Git

Version control

​
Infrastructure Setup

The service depends on shared infrastructure components from the devops repository.

​
Clone Devops Repository

First, clone and setup the devops repository: 
cd ~/projects
git clone https://github.com/e-commerce-sample/ecommerce-devops.git
cd ecommerce-devops

​
Start RabbitMQ

RabbitMQ is required for event publishing: 
cd local/rabbitmq
./start-rabbitmq.sh
RabbitMQ only needs to be started once for all Ecommerce microservices. It will continue running until you stop it.
Verify RabbitMQ is running:

​
Start Zipkin

Zipkin provides distributed tracing: 
cd local/zipkin
./start-zipkin.sh
Verify Zipkin is running:
Keep RabbitMQ and Zipkin running in the background throughout your development session.

​
Project Setup

​
Clone the Repository

cd ~/projects
git clone https://github.com/e-commerce-sample/ecommerce-order-service.git
cd ecommerce-order-service

​
Project Structure

The project is organized into two modules: 
ecommerce-order-service/
├── ecommerce-order-service-api/    # Main application
│   ├── src/
│   │   ├── main/java/              # Application code
│   │   ├── test/java/              # Unit tests
│   │   ├── componentTest/java/     # Component tests
│   │   └── apiTest/java/           # API tests
│   └── build.gradle
├── ecommerce-order-service-sdk/     # Published SDK
│   ├── src/main/java/
│   └── build.gradle
├── build.gradle                      # Root build file
├── settings.gradle
└── *.sh                              # Utility scripts

​
Build the Project

Use the Gradle wrapper to build: 
./gradlew build
This will:
  1. Compile all source code
  2. Run unit tests
  3. Run component tests
  4. Run API tests
  5. Generate build artifacts
The first build may take several minutes as Gradle downloads dependencies.

​
IDE Setup

​
IntelliJ IDEA

The project includes a script to generate IntelliJ project files: 
./idea.sh
This will:
  1. Generate IntelliJ IDEA project files
  2. Configure Gradle integration
  3. Automatically open IntelliJ IDEA
Manual Import: If you prefer to import manually:
  1. Open IntelliJ IDEA
  2. File → Open
  3. Select the ecommerce-order-service directory
  4. Choose “Open as Gradle Project”

​
Lombok Configuration

The project uses Lombok to reduce boilerplate code:
  1. Install the Lombok plugin in IntelliJ:
    • Settings → Plugins → Search “Lombok” → Install
  2. Enable annotation processing:
    • Settings → Build, Execution, Deployment → Compiler → Annotation Processors
    • Check “Enable annotation processing”

​
Running the Service

​
Using the Run Script

The simplest way to run the service: 
./run.sh
This script will:
  1. Start MySQL via Docker Compose (port 13306)
  2. Wait for MySQL to be ready
  3. Start the Spring Boot application (port 8080)
  4. Enable remote debugging (port 5005)

​
Manual Start

If you prefer to start components separately:
1

Start MySQL

./gradlew composeUp
MySQL will start on port 13306.
2

Run the application

./gradlew bootRun
Or from IntelliJ, run the Application class.

​
Verify the Service

Once started, verify the service is running: 
curl http://localhost:8080/about
You should see service metadata in the response.

​
Development Workflow

​
Make Code Changes

  1. Edit code in your IDE
  2. Save changes
  3. Restart the application to see changes

​
Run Tests

./gradlew test componentTest apiTest

​
Clean and Rebuild

./gradlew clean build

​
Debugging

​
Remote Debugging

When you run the service with ./run.sh, it listens on port 5005 for debugger connections. IntelliJ IDEA Setup:
  1. Run → Edit Configurations
  2. Add New Configuration → Remote JVM Debug
  3. Set host: localhost
  4. Set port: 5005
  5. Click Debug to attach

​
Viewing Logs

Logs are written to:
  • Console: stdout/stderr
  • File: /var/log/ecommerce-order-backend/order-dev.log (configured in application-dev.yml)
# Tail logs
tail -f /var/log/ecommerce-order-backend/order-dev.log

​
Common Issues

Another application is using port 8080.Solution:Find and stop the process:
lsof -i :8080
kill -9 <PID>
RabbitMQ is not running or not accessible.Solution:
  1. Ensure RabbitMQ is started from devops repository
  2. Verify it’s accessible at localhost:5672
  3. Check Docker containers: docker ps | grep rabbitmq
MySQL container is not running or port 13306 is blocked.Solution:
# Check if MySQL is running
docker ps | grep mysql

# Restart MySQL
./gradlew composeDown
./gradlew composeUp
Lombok annotation processing is not enabled.Solution:
  1. Install Lombok plugin in your IDE
  2. Enable annotation processing in IDE settings
  3. Rebuild project: ./gradlew clean build

​
Next Steps

Configuration

Learn about configuration options

Testing

Understand the testing strategy

API Reference

Explore the REST API

Architecture

Understand the system design

Build docs developers (and LLMs) love

Get started for freeTalk to us