Local Development Setup

Overview

This guide walks through setting up Argos Mesh for local development. You’ll learn how to run services individually, build from source, and configure your development environment.

For running the complete stack, see Docker Compose Deployment.

Prerequisites

Required Software

Java Development Kit 21

Argos Mesh uses Java 21 features including Virtual Threads.Install on Linux/macOS:

# Using SDKMAN (recommended)
curl -s "https://get.sdkman.io" | bash
sdk install java 21-tem

Verify installation:

java -version
# Should show: openjdk version "21"

Apache Maven 3.9+

Build tool for Spring Boot applications.Install on Linux/macOS:

# Using SDKMAN
sdk install maven 3.9.6

# Or using package manager
brew install maven  # macOS
sudo apt install maven  # Ubuntu/Debian

Verify installation:

mvn -version
# Should show: Apache Maven 3.9.6

Docker & Docker Compose

Required for running PostgreSQL, RabbitMQ, and Redis locally.Install Docker Desktop:

macOS/Windows: Docker Desktop
Linux: Docker Engine

Verify installation:

docker --version
docker compose version

Git

git --version

Optional Tools

IDE: IntelliJ IDEA, VS Code with Java extensions, or Eclipse
Database Client: DBeaver, pgAdmin, or psql CLI
API Testing: Postman, Insomnia, or curl
Redis Client: RedisInsight or redis-cli

Project Structure

argos-mesh/
├── orders/          # Main shop application (REST API)
│   ├── src/
│   ├── pom.xml
│   └── Dockerfile
├── sentinel/        # DDoS protection service
│   ├── src/
│   ├── pom.xml
│   └── Dockerfile
├── notify/          # Notification worker service
│   ├── src/
│   ├── pom.xml
│   └── Dockerfile
└── infra/           # Docker Compose configuration
    └── docker-compose.yml

Quick Start: Full Stack

Clone Repository

git clone <repository-url>
cd argos-mesh

Start Infrastructure Services

Start PostgreSQL, RabbitMQ, and Redis using Docker Compose:

cd infra
docker compose up -d db rabbitmq redis_db

Verify services are running:

docker compose ps

Build All Microservices

Build each service from source:

# Build Orders service
cd ../orders
mvn clean package -DskipTests

# Build Sentinel service
cd ../sentinel
mvn clean package -DskipTests

# Build Notify service
cd ../notify
mvn clean package -DskipTests

Run Services Locally

Open three terminal windows and run each service:Terminal 1 - Orders Service:

cd orders
java -jar target/orders-0.0.1.jar

Terminal 2 - Sentinel Service:

cd sentinel
java -jar target/sentinel-0.0.1.jar

Terminal 3 - Notify Service:

cd notify
java -jar target/notify-0.0.1.jar

Service-by-Service Setup

Orders Service (Main Application)

Orders Service Configuration

Technology Stack:

Spring Boot 4.0.3
Spring Data JPA (PostgreSQL)
Spring Data Redis
Spring AMQP (RabbitMQ)
Spring Web MVC
MapStruct for DTO mapping
Lombok

Build Commands:

cd orders
mvn clean package

Run the Service:

java -jar target/orders-0.0.1.jar

The Orders API will be available at: http://localhost:8080Environment Variables:You can override default configuration:

export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/shop_db
export SPRING_DATASOURCE_USERNAME=user_shop
export SPRING_DATASOURCE_PASSWORD=secretPassword
export SPRING_RABBITMQ_HOST=localhost
export SPRING_RABBITMQ_PORT=5672
export SPRING_RABBITMQ_USERNAME=admin
export SPRING_RABBITMQ_PASSWORD=admin123
export SPRING_DATA_REDIS_HOST=localhost
export SPRING_DATA_REDIS_PORT=6379

java -jar target/orders-0.0.1.jar

Sentinel Service (DDoS Protection)

Sentinel Service Configuration

Technology Stack:

Spring Boot 4.0.3
Spring AMQP (RabbitMQ consumer/publisher)
Spring Data Redis (blacklist storage)
Java 21 Virtual Threads
Jackson for JSON serialization

Key Features:

Monitors request patterns for DDoS attacks
Uses Redis to maintain IP blacklist
Publishes alerts to RabbitMQ
High concurrency with Virtual Threads

Build Commands:

cd sentinel
mvn clean package -DskipTests

Run the Service:

java -jar target/sentinel-0.0.1.jar

Environment Variables:

export SPRING_RABBITMQ_HOST=localhost
export SPRING_RABBITMQ_PORT=5672
export SPRING_RABBITMQ_USERNAME=admin
export SPRING_RABBITMQ_PASSWORD=admin123
export SPRING_DATA_REDIS_HOST=localhost
export SPRING_DATA_REDIS_PORT=6379
export SPRING_THREADS_VIRTUAL_ENABLED=true

java -jar target/sentinel-0.0.1.jar

Sentinel requires RabbitMQ and Redis to be running before it starts.

Notify Service (Alert Worker)

Notify Service Configuration

Technology Stack:

Spring Boot 4.0.3
Spring AMQP (RabbitMQ consumer)
Jackson for JSON deserialization

Key Features:

Consumes alert messages from RabbitMQ
Sends notifications for security events
Headless worker service (no HTTP endpoints)

Build Commands:

cd notify
mvn clean package -DskipTests

Run the Service:

java -jar target/notify-0.0.1.jar

Environment Variables:

export SPRING_RABBITMQ_HOST=localhost
export SPRING_RABBITMQ_PORT=5672
export SPRING_RABBITMQ_USERNAME=admin
export SPRING_RABBITMQ_PASSWORD=admin123

java -jar target/notify-0.0.1.jar

Infrastructure Services

PostgreSQL Database

PostgreSQL Setup

Start PostgreSQL:

cd infra
docker compose up -d db

Connection Details:

Host: localhost
Port: 5432
Database: shop_db
Username: user_shop
Password: secretPassword

Connect using psql:

docker compose exec db psql -U user_shop -d shop_db

Common psql Commands:

-- List all tables
\dt

-- Describe table structure
\d table_name

-- List all databases
\l

-- Quit
\q

JDBC Connection String:

jdbc:postgresql://localhost:5432/shop_db

RabbitMQ Message Broker

RabbitMQ Setup

Start RabbitMQ:

cd infra
docker compose up -d rabbitmq

Connection Details:

AMQP Port: 5672
Management UI: http://localhost:15672
Username: admin
Password: admin123

Access Management UI:

Open browser to http://localhost:15672
Login with admin / admin123
View:
- Queues and message rates
- Connections from services
- Exchange bindings
- Message flow

Useful Management Commands:

# List all queues
docker compose exec rabbitmq rabbitmqctl list_queues

# List connections
docker compose exec rabbitmq rabbitmqctl list_connections

# Purge a queue
docker compose exec rabbitmq rabbitmqctl purge_queue queue_name

Redis Cache

Redis Setup

Start Redis:

cd infra
docker compose up -d redis_db

Connection Details:

Host: localhost
Port: 6379
Password: None (default)

Connect using redis-cli:

docker compose exec redis_db redis-cli

Common Redis Commands:

# View all keys
KEYS *

# Get value of a key
GET key_name

# Check if key exists
EXISTS key_name

# View all blacklisted IPs (example)
SMEMBERS blacklist

# Get info about Redis
INFO

# Monitor commands in real-time
MONITOR

Persistence:Redis is configured with AOF (Append-Only File) persistence:

command: ["redis-server", "--appendonly", "yes"]

Data persists in the redis_data Docker volume.

Development Workflow

Using IDE (IntelliJ IDEA)

Import Project

Open IntelliJ IDEA
File → Open → Select argos-mesh directory
IntelliJ will detect Maven projects automatically

Configure JDK

File → Project Structure → Project
Set SDK to Java 21
Set Language Level to 21

Run Configuration

Create run configurations for each service:

Run → Edit Configurations
Add new Spring Boot configuration
Main class: Auto-detected
Environment variables: Set as needed

Enable Lombok

Settings → Plugins → Install Lombok plugin
Settings → Build → Compiler → Annotation Processors
Enable annotation processing

Hot Reload with Spring DevTools

Add Spring DevTools to pom.xml for automatic restarts:

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

Reload automatically when you save changes in your IDE.

Testing

mvn test

Accessing Services

Service Ports

Service	Port	URL
Orders API	8080	http://localhost:8080
PostgreSQL	5432	jdbc:postgresql://localhost:5432/shop_db
RabbitMQ AMQP	5672	amqp://localhost:5672
RabbitMQ Management	15672	http://localhost:15672
Redis	6379	redis://localhost:6379

Testing the Orders API

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

Troubleshooting

Port already in use

Error: Port 8080 is already in useSolution:Find and kill the process:

# Find process using port
lsof -i :8080

# Kill process
kill -9 <PID>

Or change the port:

java -jar target/orders-0.0.1.jar --server.port=8081

Maven build fails

Error: Failed to execute goalSolutions:

Clean Maven cache:

mvn clean install -U

Delete .m2/repository and rebuild:

rm -rf ~/.m2/repository
mvn clean package

Ensure Java 21 is active:

java -version

Database connection refused

Error: Connection refused: localhost:5432Solutions:

Verify PostgreSQL is running:

docker compose ps db

Check database logs:

docker compose logs db

Test connection:

docker compose exec db pg_isready -U user_shop

RabbitMQ connection timeout

Error: Timeout waiting for RabbitMQ connectionSolutions:

Verify RabbitMQ is running:

docker compose ps rabbitmq

Check health:

docker compose exec rabbitmq rabbitmq-diagnostics ping

Access management UI to verify: http://localhost:15672

Redis connection failed

Error: Unable to connect to RedisSolutions:

Verify Redis is running:

docker compose ps redis_db

Test connection:

docker compose exec redis_db redis-cli ping
# Should return: PONG

Java version mismatch

Error: class file has wrong versionSolution:Ensure Java 21 is active:

java -version
javac -version

# If using SDKMAN
sdk use java 21-tem

# Set JAVA_HOME
export JAVA_HOME=$(/usr/libexec/java_home -v 21)

Out of memory errors

Error: Java heap spaceSolution:Increase heap size:

java -Xmx512m -Xms256m -jar target/orders-0.0.1.jar

Development Tips

Use Profiles

Create different application-{profile}.properties files for dev/test/prod configurations.

Enable Debug Logging

Add to application.properties:

logging.level.com.argos=DEBUG

Use Docker Compose Profiles

Start only infrastructure:

docker compose up -d db rabbitmq redis_db

Monitor with Actuator

Add Spring Boot Actuator for metrics and health checks at /actuator.

Next Steps

Docker Compose Deployment

Deploy the complete stack with one command

API Reference

Explore the REST API endpoints

Architecture Overview

Understand the system architecture

Security Features

Learn about DDoS protection

Deployment

Security

​Overview

​Prerequisites

​Required Software

​Optional Tools

​Project Structure

​Quick Start: Full Stack

​Service-by-Service Setup

​Orders Service (Main Application)

​Sentinel Service (DDoS Protection)

​Notify Service (Alert Worker)

​Infrastructure Services

​PostgreSQL Database

​RabbitMQ Message Broker

​Redis Cache

​Development Workflow

​Using IDE (IntelliJ IDEA)

​Hot Reload with Spring DevTools

​Testing

​Accessing Services

​Service Ports

​Testing the Orders API

​Troubleshooting

​Development Tips

Use Profiles

Enable Debug Logging

Use Docker Compose Profiles

Monitor with Actuator

​Next Steps

Docker Compose Deployment

API Reference

Architecture Overview

Security Features

Build docs developers (and LLMs) love

Overview

Prerequisites

Required Software

Optional Tools

Project Structure

Quick Start: Full Stack

Service-by-Service Setup

Orders Service (Main Application)

Sentinel Service (DDoS Protection)

Notify Service (Alert Worker)

Infrastructure Services

PostgreSQL Database

RabbitMQ Message Broker

Redis Cache

Development Workflow

Using IDE (IntelliJ IDEA)

Hot Reload with Spring DevTools

Testing

Accessing Services

Service Ports

Testing the Orders API

Troubleshooting

Development Tips

Next Steps