πŸš€ Deployment Guide

This guide covers all supported ways to deploy ATLAS β€” from a quick local setup to a production cloud environment.


Table of Contents


The fastest way to run the full ATLAS stack.

Prerequisites

Tool Minimum Version Check
Docker 24.0 docker --version
Docker Compose 2.20 docker compose version
Git 2.30 git --version
RAM 4 GB free β€”
Disk 5 GB free β€”

Step-by-step

1. Clone the repository (with all submodules)

git clone --recurse-submodules https://github.com/cepdnaclk/e22-co2060-hydro-risk-management.git
cd e22-co2060-hydro-risk-management

If you already cloned without submodules:

git submodule update --init --recursive

2. Set up environment variables

cp .env.example .env

Open .env in a text editor and update at minimum:

3. Build and start all services

docker compose up --build -d

This starts 9 containers. First boot takes 3–5 minutes while:

4. Check all services are running

docker compose ps

Expected output:

NAME                         STATUS          PORTS
master_timescaledb           running         0.0.0.0:5432->5432/tcp
redis_cache                  running         0.0.0.0:6379->6379/tcp
metadata-handling-service    running         0.0.0.0:8092->8092/tcp
alerting-service             running         0.0.0.0:8093->8093/tcp
mqtt-subscriber-service      running         0.0.0.0:8091->8091/tcp
report-generating-service    running         0.0.0.0:8094->8094/tcp
user-service                 running         0.0.0.0:8096->8096/tcp
gis-monitoring-service       running         0.0.0.0:8097->8097/tcp
frontend                     running         0.0.0.0:8090->80/tcp

5. Access the application

URL Description
http://localhost:8090 🌐 Main Dashboard (login: admin / admin123)
http://localhost:8092/swagger-ui.html πŸ“‹ Metadata API docs
http://localhost:8096/swagger-ui.html πŸ‘€ Auth API docs

Option 2: Manual / Local Development

Use this approach when developing or modifying ATLAS services.

Start the database and Redis only

docker compose up db redis -d

Run each service manually

Backend service (example: alerting service)

cd disaster-management-alerting-service

# Using Maven wrapper (recommended)
./mvnw spring-boot:run

# On Windows
mvnw.cmd spring-boot:run

Make sure each service’s application.yml points to localhost:5432 (not db:5432).

Frontend

cd disaster-management-frontend
npm install
npm run dev
# Runs at http://localhost:5173

Service startup order (for manual setup)

1. db (TimescaleDB)     ← Start first, wait ~30s
2. redis               ← Start second
3. user-service        ← Required by other services for JWT validation
4. metadata-service    ← Core entity data
5. mqtt-service        ← Starts ingesting data immediately
6. alerting-service    ← Reads sensor data, generates alerts
7. gis-service         ← Reads sensors + alerts for map
8. report-service      ← Reads historical data
9. frontend            ← Calls all backend services

Option 3: Cloud Deployment

AWS (EC2 + RDS)

Architecture:

Internet β†’ ALB β†’ EC2 (Docker Services)
                      β†’ RDS (PostgreSQL + TimescaleDB extension)
                      β†’ ElastiCache (Redis)

Steps:

  1. Provision RDS β€” Use PostgreSQL 14 engine. Enable TimescaleDB extension:
    CREATE EXTENSION IF NOT EXISTS timescaledb;
    
  2. Provision ElastiCache β€” Redis cluster, single node is sufficient for token blacklisting.

  3. Set environment variables on EC2:
    export SPRING_DATASOURCE_URL=jdbc:postgresql://your-rds-endpoint:5432/kernelx
    export SPRING_DATA_REDIS_HOST=your-elasticache-endpoint
    
  4. Deploy with Docker Compose on EC2 (comment out db and redis services, they’re now managed):
    docker compose up --build -d \
      metadata-handling-service \
      alerting-service \
      mqtt-service \
      report-generating-service \
      user-service \
      gis-monitoring-service \
      frontend
    
  5. Configure ALB to route traffic to port 8090 (or add Nginx in front).

Google Cloud (GKE)

A Kubernetes deployment guide is available as a community contribution. See discussions.

Docker Swarm

# Initialize swarm
docker swarm init

# Deploy the stack
docker stack deploy -c docker-compose.yml atlas

Production Checklist

Before going live, work through this checklist:

Security

Database

Infrastructure

Monitoring


Health Checks

Each Spring Boot service exposes Spring Actuator health endpoints:

# Check a service health
curl http://localhost:8092/actuator/health

# Expected response when healthy
{"status":"UP","components":{"db":{"status":"UP"},"redis":{"status":"UP"}}}

Quick health check for all services:

for port in 8091 8092 8093 8094 8096 8097; do
  echo -n "Service :$port β€” "
  curl -s http://localhost:$port/actuator/health | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('status','UNKNOWN'))"
done

Logs & Monitoring

View logs via Docker Compose

# All services
docker compose logs -f

# Specific service (follow)
docker compose logs -f alerting-service

# Last 100 lines of user service
docker compose logs --tail=100 user-service

Log format

All Spring Boot services use Logback with structured logging. Key log levels:

Level Meaning
INFO Normal operation, scheduled job results
WARN Data validation failures, non-critical issues
ERROR Exceptions, DB connection failures
DEBUG Detailed request/response (disabled in production)

Updating ATLAS

Update submodules to their latest commits

git submodule update --remote --merge
git add .
git commit -m "chore: update all submodules to latest"

Rebuild and restart changed services

# Rebuild all (safe, preserves volumes)
docker compose up --build -d

# Rebuild a specific service only
docker compose up --build -d alerting-service

Troubleshooting

Services fail to start (DB not ready)

Spring Boot services may start before TimescaleDB finishes initializing. Wait 30–60 seconds and run:

docker compose restart metadata-handling-service alerting-service

Or, to avoid this, add health checks to docker-compose.yml:

depends_on:
  db:
    condition: service_healthy

MQTT not receiving data

  1. Check the broker and topic are correct in application.yml
  2. Check the MQTT service logs: docker compose logs mqtt-subscriber-service
  3. Use MQTT Explorer to verify your device is publishing
  4. Verify the topic pattern β€” thw/telemetry/# uses wildcard # for any sub-topic

Frontend cannot reach backend services

The frontend uses Nginx as a reverse proxy. Check disaster-management-frontend/nginx.conf to ensure proxy_pass URLs are correct for your environment.

Port conflicts

If any port is already in use, edit the left side of the port mapping in docker-compose.yml:

ports:
  - "18092:8092"  # Use 18092 on host if 8092 is taken

Database connection refused

# Check if TimescaleDB is running
docker compose ps db

# Connect to DB manually to verify
docker exec -it master_timescaledb psql -U kernelx -d kernelx

# Check if tables exist
\dt