Discovery Server

Overview

sgivu-discovery is the service discovery server (Eureka Server) for the SGIVU ecosystem. It registers and displays microservice instances, enables service name resolution, and serves as the central source for simple load balancing between services.

Technologies

Java: 21
Spring Boot: 3.5.8
Spring Cloud Netflix Eureka Server: Service registry
Spring Cloud Config: Client for centralized configuration
Spring Boot Devtools: Hot reload during development

Port Configuration

Default Port: 8761
Dashboard: http://localhost:8761/

Prerequisites

JDK 21
Maven 3.9+
Docker & docker-compose
Recommended: Launch full stack with infra/compose/sgivu-docker-compose/docker-compose.dev.yml including sgivu-config

Endpoints

http://<host>:8761/

Eureka dashboard showing all registered applications and their instances

GET /eureka/apps

XML/JSON

REST API listing all registered applications

GET /eureka/apps/{appName}

XML/JSON

Information about specific application and its instances

GET /eureka/apps/{appName}/{instanceId}

XML/JSON

Detailed information about specific instance

GET /actuator/health

JSON

Service health status (if Actuator is enabled)

Running the Service

Development with Docker Compose

cd infra/compose/sgivu-docker-compose
docker compose -f docker-compose.dev.yml up -d

This starts sgivu-config (native mode) and sgivu-discovery along with other services.

Local Execution

./mvnw clean package
./mvnw spring-boot:run

Docker Build

./build-image.bash
docker build -t stevenrq/sgivu-discovery:v1 .
docker run -p 8761:8761 stevenrq/sgivu-discovery:v1

Dashboard UI

Access the Eureka dashboard at http://localhost:8761/:

Dashboard displays:

System status and environment information
Registered instances per application
Instance status (UP, DOWN, OUT_OF_SERVICE)
Renewal threshold and last renewal time
General info about replicas (if configured)

Client Configuration

Microservices register with Eureka using this configuration:

spring:
  application:
    name: sgivu-user  # Unique name per service

eureka:
  client:
    service-url:
      defaultZone: http://sgivu-discovery:8761/eureka/
    register-with-eureka: true
    fetch-registry: true
  instance:
    prefer-ip-address: true
    lease-renewal-interval-in-seconds: 30
    lease-expiration-duration-in-seconds: 90

Ensure each service has a unique spring.application.name - this is used as the service identifier in Eureka.

Service Registration Flow

Startup: Service starts and reads Eureka configuration
Registration: Service sends registration request to Eureka server
Heartbeat: Service sends renewals every 30 seconds (default)
Discovery: Other services fetch registry to locate service instances
Deregistration: Service unregisters on graceful shutdown

Load Balancing

Eureka enables client-side load balancing:

// Spring Cloud LoadBalancer automatically uses Eureka registry
@LoadBalanced
@Bean
public WebClient.Builder webClientBuilder() {
    return WebClient.builder();
}

// Use service name in URL
webClient.get()
    .uri("http://sgivu-user/v1/users/{id}", userId)
    .retrieve()
    .bodyToMono(User.class);

High Availability

Standalone Mode (Development)

eureka:
  client:
    register-with-eureka: false
    fetch-registry: false

Cluster Mode (Production)

Multiple Eureka instances register with each other:

# Eureka instance 1
eureka:
  client:
    service-url:
      defaultZone: http://eureka2:8761/eureka/,http://eureka3:8761/eureka/

For production deployments, run at least 2 Eureka instances for high availability.

Security

Network Security

Eureka server should be accessible only within private network
Use VPC/security groups to restrict access in cloud deployments
Consider adding Spring Security for authentication if exposing dashboard

Client Authentication

Ensure Eureka clients:

Have correct defaultZone configuration
Use unique spring.application.name per service
Register with appropriate metadata for routing

Observability

Service Monitoring

Via Dashboard:

Monitor registered instances count
Check instance status (UP/DOWN)
Review last heartbeat times
Verify renewal threshold

Via REST API:

# List all services
curl http://localhost:8761/eureka/apps

# Check specific service
curl http://localhost:8761/eureka/apps/SGIVU-USER

Health Checks

curl http://localhost:8761/actuator/health

Distributed Tracing

Eureka server doesn’t include tracing dependencies by default. Enable Micrometer/Zipkin in other services and review registration status in Eureka dashboard.

Testing

./mvnw test

Recommended Integration Tests:

Simulate instance registration
Verify visibility in /eureka/apps endpoint
Test heartbeat and expiration behavior
Validate service discovery by name

Instance Metadata

Clients can add custom metadata:

eureka:
  instance:
    metadata-map:
      version: 1.0.0
      region: us-east-1
      environment: dev

Access metadata in consumers:

List<ServiceInstance> instances = discoveryClient.getInstances("sgivu-user");
String version = instances.get(0).getMetadata().get("version");

Self-Preservation Mode

Eureka enters self-preservation when too many instances fail to send heartbeats: Behavior:

Eureka stops evicting instances
Dashboard shows warning message
Prevents network partition issues

Disable in Development:

eureka:
  server:
    enable-self-preservation: false

Always keep self-preservation enabled in production to prevent cascading failures during network issues.

Troubleshooting

No services appearing in dashboard

Symptoms: Eureka dashboard shows no registered applicationsSolutions:

Verify clients have eureka.client.service-url.defaultZone set to http://sgivu-discovery:8761/eureka/
Check eureka.client.register-with-eureka: true in client config
Ensure clients can reach Eureka server (network connectivity)
Review client logs for registration errors
Verify Docker network if using containers

Network connectivity errors

Symptoms: Services can’t connect to Eureka serverSolutions:

Check Docker networks configuration
Verify sgivu-config is accessible and returning correct Eureka URL
Ensure port 8761 is not blocked by firewall
Test connectivity: curl http://sgivu-discovery:8761/eureka/apps

Port already in use

Symptoms: Eureka fails to start with “Address already in use” errorSolutions:

Check if another process is using port 8761: lsof -i :8761
Kill existing process or change Eureka port
Verify Docker isn’t running duplicate Eureka containers

Services not discovering each other

Symptoms: Service-to-service calls fail with “no such host” or 404Solutions:

Verify both services are registered in Eureka dashboard
Check spring.application.name matches the name used in URLs
Ensure consumers have eureka.client.fetch-registry: true
Verify @LoadBalanced annotation on RestTemplate/WebClient
Wait 30-60 seconds after registration for cache refresh

Instances stuck in DOWN state

Symptoms: Instances show as DOWN despite being healthySolutions:

Check instance health endpoint is accessible
Verify eureka.instance.prefer-ip-address setting
Review heartbeat configuration (renewal interval)
Check for network issues between instance and Eureka
Force instance removal and re-registration

Environment Variables

Variable	Description	Default
`PORT`	Server port	`8761`
`EUREKA_URL`	Eureka server URL (for clients)	`http://localhost:8761/eureka/`
`SPRING_APPLICATION_NAME`	Application name	`sgivu-discovery`

Configuration Reference

Server Configuration

eureka:
  server:
    enable-self-preservation: true
    eviction-interval-timer-in-ms: 60000
    response-cache-update-interval-ms: 30000

Client Configuration

eureka:
  client:
    registry-fetch-interval-seconds: 30
    instance-info-replication-interval-seconds: 30
  instance:
    lease-renewal-interval-in-seconds: 30
    lease-expiration-duration-in-seconds: 90

Best Practices

Unique Names

Use unique spring.application.name for each service

HA Setup

Run multiple Eureka instances in production

Health Checks

Implement custom health indicators for accurate status

Metadata

Use metadata for routing and filtering instances

Config Server

Centralized configuration including Eureka URLs

Gateway

Uses Eureka for routing to downstream services

All Services

All services register with Eureka

Services

​Overview

​Technologies

​Port Configuration

​Prerequisites

​Endpoints

​Running the Service

​Development with Docker Compose

​Local Execution

​Docker Build

​Dashboard UI

​Client Configuration

​Service Registration Flow

​Load Balancing

​High Availability

​Standalone Mode (Development)

​Cluster Mode (Production)

​Security

​Network Security

​Client Authentication

​Observability

​Service Monitoring

​Health Checks

​Distributed Tracing

​Testing

​Instance Metadata

​Self-Preservation Mode

​Troubleshooting

​Environment Variables

​Configuration Reference

​Server Configuration

​Client Configuration

​Best Practices

Unique Names

HA Setup

Health Checks

Metadata

​Related Services

Config Server

Gateway

All Services

Build docs developers (and LLMs) love

Overview

Technologies

Port Configuration

Prerequisites

Endpoints

Running the Service

Development with Docker Compose

Local Execution

Docker Build

Dashboard UI

Client Configuration

Service Registration Flow

Load Balancing

High Availability

Standalone Mode (Development)

Cluster Mode (Production)

Security

Network Security

Client Authentication

Observability

Service Monitoring

Health Checks

Distributed Tracing

Testing

Instance Metadata

Self-Preservation Mode

Troubleshooting

Environment Variables

Configuration Reference

Server Configuration

Client Configuration

Best Practices

Related Services