Skip to content

Deployment Guide

This guide explains how to build, run, configure and troubleshoot the system. The whole stack is containerised and orchestrated with Docker Compose.

Prerequisites

  • Docker and Docker Compose installed.
  • Java 21 and Gradle — only needed for local (non-Docker) builds. The Docker images build the services themselves using a Gradle base image, so a local JDK is not required just to run the stack.

Components Started

docker-compose up brings up the following containers:

Container Image Host ports Role
caddy caddy:2 8080, 8081 API gateway / reverse proxy.
rabbitmq rabbitmq:3.13-management 5672, 15672 Message broker + management UI.
mongodb mongo:latest 27017 Persistence (SAGA state, event store).
customer built from customer/ (internal 8080) Customer Service.
delivery built from delivery/ (internal 8080) Delivery Service.
drone built from drone/ (internal 8080) Drone Service.
prometheus prom/prometheus:latest (via gateway) Metrics scraping.

The three application services are not published directly to the host — they are reached only through the Caddy gateway on port 8080.

Build Steps

  1. Build all services locally (optional — Compose can build for you): sh ./gradlew build
  2. Build the Docker images: sh docker-compose build

Running the System

  1. Start everything (building images if needed): sh docker-compose up --build
  2. Useful URLs once the stack is healthy:
  3. API gateway: http://localhost:8080
  4. Caddy admin API: http://localhost:8081
  5. RabbitMQ management UI: http://localhost:15672 (user guest, password guest)
  6. Prometheus: http://localhost:8080/prometheus

End-to-end smoke test

The repository ships a convenience script that boots the stack, submits a sample order, waits for the SAGA to finish and checks the logs for COMPLETED:

./teste2e.sh

Stopping the System

docker-compose down

Add -v to also remove the named volumes (mongo_data, caddy_data, caddy_config) and wipe persisted state.

Configuration

Configuration is supplied through each service's application.yml and overridden via environment variables (set in docker-compose.yml):

Variable Used by Default (local) In Compose
RABBITMQ_HOST all services localhost rabbitmq
RABBITMQ_USER all services guest guest
RABBITMQ_PASS all services guest guest
MONGODB_URI customer, drone mongodb://localhost:27017/<service>_db mongodb://mongodb:27017/<service>_db

Each service uses its own MongoDB database: customer_db, delivery_db, drone_db.

Tracing & metrics are configured under management: in each application.yml — tracing sampling is set to 1.0 (100%), and the health and prometheus Actuator endpoints are exposed.

Health Endpoints

Service Application health Actuator health
Customer /api/orders/health /customer/actuator/health
Drone /api/drones/health /drone/actuator/health

Docker Compose health checks call these endpoints, and dependent services wait for RabbitMQ to be healthy before starting.

Troubleshooting

  • Inspect logs: docker-compose logs <service> (e.g. docker-compose logs customer). Note that infrastructure containers (caddy, rabbitmq, mongodb, prometheus) have logging disabled in docker-compose.yml; remove the logging: driver: "none" block to see their logs.
  • Port conflicts: ensure 8080, 8081, 15672, 5672 and 27017 are free on the host.
  • A SAGA never completes: check the RabbitMQ management UI for stuck messages and look for FAILED / COMPENSATING in the customer logs; query GET /api/orders/{orderId}/saga-status.
  • No metrics in Prometheus: confirm the services are up and that /<service>/actuator/prometheus returns data; Prometheus scrapes the services directly on the Docker network (see prometheus.yml).