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
- Build all services locally (optional — Compose can build for you):
sh ./gradlew build - Build the Docker images:
sh docker-compose build
Running the System
- Start everything (building images if needed):
sh docker-compose up --build - Useful URLs once the stack is healthy:
- API gateway: http://localhost:8080
- Caddy admin API: http://localhost:8081
- RabbitMQ management UI: http://localhost:15672 (user
guest, passwordguest) - 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 indocker-compose.yml; remove thelogging: driver: "none"block to see their logs. - Port conflicts: ensure
8080,8081,15672,5672and27017are free on the host. - A SAGA never completes: check the RabbitMQ management UI for stuck messages and look for
FAILED/COMPENSATINGin the customer logs; queryGET /api/orders/{orderId}/saga-status. - No metrics in Prometheus: confirm the services are up and that
/<service>/actuator/prometheusreturns data; Prometheus scrapes the services directly on the Docker network (seeprometheus.yml).