Config Server

Overview

sgivu-config is the central configuration server for the SGIVU ecosystem. Using Spring Cloud Config Server, it exposes centralized configuration from a Git repository or local filesystem (native mode), allowing microservices to retrieve properties based on application, profile, and label.

Technologies

Java: 21
Spring Boot: 3.5.8
Spring Cloud Config Server: 2025.x
Spring Boot Actuator: Health monitoring

Port Configuration

Default Port: 8888

Prerequisites

JDK 21
Maven 3.9+
Docker & docker-compose (optional)
Access to configuration repository: https://github.com/stevenrq/sgivu-config-repo.git
- Or local copy for native mode

Endpoints

GET /{application}/{profile}

JSON

Returns properties for specified application and profileExample: GET /sgivu-auth/dev

GET /{application}/{profile}/{label}

JSON

Returns properties with specific label (Git branch)Example: GET /sgivu-auth/prod/main

GET /{application}-{profile}.yml

YAML

Returns configuration file in YAML formatExample: GET /sgivu-auth-dev.yml

GET /actuator/health

JSON

Service health status

Running the Service

Development with Docker Compose

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

Development mode uses native profile with local repository mounted as volume.

Local Execution

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

Docker Build

./build-image.bash
docker run -p 8888:8888 --env-file .env stevenrq/sgivu-config:v1

Configuration Modes

Git Mode (Production)

Default configuration in src/main/resources/application.yml:

spring:
  profiles:
    active: git
  cloud:
    config:
      server:
        git:
          uri: https://github.com/stevenrq/sgivu-config-repo.git
          default-label: main
          clone-on-start: true

Features:

Pulls configuration from remote Git repository
Supports branch selection via label parameter
Automatic updates when repository changes
Secure for production use

Native Mode (Development)

Configured in docker-compose for local development:

spring:
  profiles:
    active: native
  cloud:
    config:
      server:
        native:
          search-locations: file:///config-repo

Features:

Reads from local filesystem
Fast iteration during development
No network dependency
Mounted as Docker volume

Usage Examples

Fetch Configuration

# Get dev configuration for auth service
curl http://localhost:8888/sgivu-auth/dev

# Get prod configuration with specific branch
curl http://localhost:8888/sgivu-gateway/prod/main

# Get raw YAML file
curl http://localhost:8888/sgivu-user-dev.yml

Response Format

{
  "name": "sgivu-auth",
  "profiles": ["dev"],
  "label": "main",
  "version": "abc123def456",
  "state": null,
  "propertySources": [
    {
      "name": "https://github.com/stevenrq/sgivu-config-repo.git/sgivu-auth-dev.yml",
      "source": {
        "server.port": 9000,
        "spring.datasource.url": "jdbc:postgresql://...",
        "...": "..."
      }
    }
  ]
}

Client Configuration

Microservices connect to config server using:

spring:
  application:
    name: sgivu-auth
  config:
    import: optional:configserver:http://sgivu-config:8888
  cloud:
    config:
      fail-fast: true
      retry:
        max-attempts: 6
        initial-interval: 1000

Set fail-fast: true in production to prevent services from starting with incorrect configuration.

Security

Development

Uses native mode with local repository mount
No authentication required for internal network

Production

Uses Git mode with remote repository
Repository access controlled via Git credentials
Consider using private repository with authentication
Encrypt sensitive properties using Spring Cloud Config encryption

Sensitive Data

Never commit sensitive data directly to config repository:

Database passwords
API keys
OAuth2 client secrets
JWT keystore passwords

Use environment variable placeholders: ${DB_PASSWORD}

Property Encryption

Spring Cloud Config supports encrypted properties:

# Encrypted property (example)
spring:
  datasource:
    password: '{cipher}AQA4x8K8v...'

Setup:

Configure encryption key
Use /encrypt endpoint to encrypt values
Store encrypted values in config files
Config server decrypts before serving to clients

Observability

Health Check

curl http://localhost:8888/actuator/health

Response:

{
  "status": "UP",
  "components": {
    "diskSpace": {"status": "UP"},
    "ping": {"status": "UP"}
  }
}

Monitoring

Monitor /actuator/health for service availability
Track request metrics for configuration endpoint access
Enable additional actuator endpoints in dev profile

Testing

./mvnw test

Recommended Tests:

Verify Git repository connectivity
Test native mode with local files
Validate property parsing for each service
Test profile and label resolution

Refresh Configuration

Clients can refresh configuration without restart:

# Trigger refresh on client service
curl -X POST http://client-service:port/actuator/refresh

Requires @RefreshScope annotation on beans that should be refreshed.

Troubleshooting

Git URI inaccessible

Symptoms: Config server fails to start or returns 500 errorsSolutions:

Verify SPRING_CLOUD_CONFIG_SERVER_GIT_URI environment variable
Check network access to Git repository
Verify Git credentials if using private repository
Review config server logs for connection errors

Changes not reflected

Symptoms: Services still use old configuration valuesSolutions:

Verify correct label (branch) is being used
Add /?label=branch-name to request
Restart config server to clear cache (native mode)
Trigger /actuator/refresh on client services
Check if using @RefreshScope on configuration beans

Application not found

Symptoms: Config server returns empty configurationSolutions:

Verify file naming: {application}-{profile}.yml
Check spring.application.name in client matches file name
Ensure file exists in repository root or search-locations
Review config server logs for file resolution

Property resolution fails

Symptoms: Clients fail to start with property binding errorsSolutions:

Validate YAML syntax in configuration files
Check for missing environment variable placeholders
Verify property types match expected values
Test configuration endpoint directly: /app/profile

Configuration Repository Structure

sgivu-config-repo/
├── application.yml          # Common properties for all services
├── application-dev.yml      # Common dev properties
├── application-prod.yml     # Common prod properties
├── sgivu-auth-dev.yml      # Auth service dev config
├── sgivu-auth-prod.yml     # Auth service prod config
├── sgivu-gateway.yml       # Gateway common config
├── sgivu-gateway-dev.yml   # Gateway dev config
├── sgivu-user-dev.yml      # User service dev config
├── sgivu-client-dev.yml    # Client service dev config
├── sgivu-vehicle-dev.yml   # Vehicle service dev config
└── ...

Environment Variables

Variable	Description	Default
`PORT`	Server port	`8888`
`SPRING_PROFILES_ACTIVE`	Active profile (git/native)	`git`
`SPRING_CLOUD_CONFIG_SERVER_GIT_URI`	Git repository URL	GitHub repo
`SPRING_CLOUD_CONFIG_SERVER_GIT_DEFAULT_LABEL`	Default branch	`main`
`SPRING_CLOUD_CONFIG_SERVER_NATIVE_SEARCH_LOCATIONS`	Native mode path	`file:///config-repo`

Best Practices

Use Git Mode

Use Git mode in production for version control and audit trail

Encrypt Secrets

Use Spring Cloud Config encryption for sensitive values

Environment Variables

Use placeholders for environment-specific values

Profile Hierarchy

Use common files + profile-specific overrides

Discovery

Service registry and discovery

Gateway

API Gateway configuration

Auth

Authorization server settings

All Services

Complete service overview

Services

​Overview

​Technologies

​Port Configuration

​Prerequisites

​Endpoints

​Running the Service

​Development with Docker Compose

​Local Execution

​Docker Build

​Configuration Modes

​Git Mode (Production)

​Native Mode (Development)

​Usage Examples

​Fetch Configuration

​Response Format

​Client Configuration

​Security

​Development

​Production

​Sensitive Data

​Property Encryption

​Observability

​Health Check

​Monitoring

​Testing

​Refresh Configuration

​Troubleshooting

​Configuration Repository Structure

​Environment Variables

​Best Practices

Use Git Mode

Encrypt Secrets

Environment Variables

Profile Hierarchy

​Related Services

Discovery

Gateway

Auth

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

Configuration Modes

Git Mode (Production)

Native Mode (Development)

Usage Examples

Fetch Configuration

Response Format

Client Configuration

Security

Development

Production

Sensitive Data

Property Encryption

Observability

Health Check

Monitoring

Testing

Refresh Configuration

Troubleshooting

Configuration Repository Structure

Environment Variables

Best Practices

Related Services