Platform Config Server

Spring Boot 3.x + Spring Cloud Config Server for centralized configuration management.

Documentation

• QUICKSTART.md - Get started in 5 minutes
• DEVELOPMENT.md - Complete development guide for IntelliJ IDEA
• CLAUDE.md - Architecture and technical details
• README.md - This file (comprehensive reference)

Features

• Spring Cloud Config Server with Git backend
• Custom YAML endpoint that returns merged configuration as application.yaml
• GitHub authentication support via environment variables
• Standard Config Server endpoints (JSON and YAML)
• Health checks via Spring Actuator
• Docker support with multi-stage build

Configuration Repository

• Git Repository: https://github.com/dsrvlabs/platform-config
• Directory structure: Each service has its own directory with environment-specific files

  {service}/
    |- application-{env}.yaml
    |- application-{env}.yaml
  

  • Example:

    wallet-gateway-api/
      |- application-dev.yaml
      |- application-prod.yaml
    

Prerequisites

• Java 21
• Maven 3.9+ (or use included Maven wrapper)
• Docker (optional, for containerized deployment)

Getting Started

Local Development

1. Clone the repository

   git clone https://github.com/dsrvlabs/platform-config-server.git
   cd platform-config-server

2. Set environment variables (optional, for private repositories)

   export GIT_USERNAME=your-github-username
   export GIT_TOKEN=ghp_your_personal_access_token

3. Run the application

   ./mvnw spring-boot:run

   The server will start on http://localhost:8080/config

Docker Deployment

1. Build Docker image

   docker build -t config-server:latest .

2. Run container

   docker run --rm -p 8080:8080 \
     -e GIT_USERNAME=your-github-username \
     -e GIT_TOKEN=ghp_your_token \
     config-server:latest

API Endpoints

Custom YAML Endpoint

Returns merged configuration as a downloadable application.yaml file.

# Download configuration for wallet-gateway-api service in dev environment
curl -L -o application.yaml \
  "http://localhost:8080/config/wallet-gateway-api/dev"

# With custom git label (branch/tag/commit)
curl -L -o application.yaml \
  "http://localhost:8080/config/wallet-gateway-api/dev?label=main"

Mapping: Request path /{service}/{env} maps to file {service}/application-{env}.yaml

Custom .env Endpoint

Returns configuration as a downloadable .env file in KEY=VALUE format.

# Download .env configuration for wallet-gateway-api service in qa environment
curl -L -o .env \
  "http://localhost:8080/config/wallet-gateway-api-qa.env"

# With custom git label (branch/tag/commit)
curl -L -o .env \
  "http://localhost:8080/config/wallet-gateway-api-qa.env?label=main"

Mapping: Request path /{service}-{env}.env maps to file {service}/application-{env}.env

How it works:

• Parses properties from {service}/application-{env}.env file
• Converts to .env format (KEY=VALUE)
• Returns as plain text file with appropriate filename

Example:

# Request
curl -L -o .env "http://localhost:8080/config/wallet-gateway-api-qa.env"

# Maps to repository file: wallet-gateway-api/application-qa.env
# Returns: KEY1=VALUE1\nKEY2=VALUE2\n...

Standard Spring Cloud Config Endpoints

JSON Format

⚠️ Note: The /{name}/{profile} format may not work correctly with the current directory structure ({service}/application-{env}.yaml). Use the /{name}-{profile}.yaml format (see YAML Format section below) for reliable access to configuration files.

# Returns full environment with property sources (may not work with current structure)
# This format expects files like: wallet-gateway-api-prod.yaml or wallet-gateway-api/prod.yaml
curl "http://localhost:8080/config/wallet-gateway-api/prod"

# With explicit label (branch/tag)
curl "http://localhost:8080/config/wallet-gateway-api/prod/main"

URL Pattern: /{name}/{profile} or /{name}/{profile}/{label}

• name: Service name (e.g., wallet-gateway-api)
• profile: Environment (e.g., dev, prod)
• label: Git branch/tag (optional, defaults to main)

Limitation: This format searches for files like {name}-{profile}.yaml or {name}/{profile}.yaml, but our repository structure uses {name}/application-{profile}.yaml. Recommended: Use the /{name}-{profile}.yaml format instead (see YAML Format section).

YAML Format (Recommended)

Returns the original YAML file content directly from the Git repository.

# Download original YAML file for wallet-gateway-api service in prod environment
curl -L -o application.yaml \
  "http://localhost:8080/config/wallet-gateway-api-prod.yaml"

# Download for dev environment
curl -L -o application.yaml \
  "http://localhost:8080/config/wallet-gateway-api-dev.yaml"

URL Pattern: /{name}-{profile}.yaml

• name: Service name (e.g., wallet-gateway-api)
• profile: Environment (e.g., dev, prod)

How it works:

요청: /config/wallet-gateway-api-prod.yaml
  ↓
파싱: name=wallet-gateway-api, profile=prod
  ↓
Search Paths: ["."] + ["wallet-gateway-api"]
  ↓
파일 검색: wallet-gateway-api/application-prod.yaml
  ↓
발견 및 반환: 원본 YAML 파일 내용

Spring Cloud Config automatically resolves the file path using the search-paths configuration:

1. Parses the URL to extract name and profile
2. Searches in root directory (.) and service directory ({name})
3. Matches the file pattern: {name}/application-{profile}.yaml
4. Returns the original YAML file content without any transformation

Note: Other Spring Cloud Config endpoint formats like /{name}/{profile}.yml may not work correctly with the current directory structure ({service}/application-{env}.yaml). Always use the /{name}-{profile}.yaml format for reliable access.

Health Check

curl "http://localhost:8080/config/actuator/health"

Testing

Run all tests

./mvnw test

Run integration tests

Integration tests are disabled by default as they require GitHub access. To run them:

1. Set environment variables:

   export GIT_USERNAME=your-username
   export GIT_TOKEN=your-token

2. Enable tests by removing @Disabled annotation in ConfigServerIT.java

3. Run tests:

   ./mvnw test

Configuration

Configuration is managed in src/main/resources/application.yml:

• Server Port: 8080
• Context Path: /config
• Git URI: https://github.com/dsrvlabs/platform-config
• Default Branch: main
• Clone on Start: true (downloads repo on startup)
• Force Pull: true (always pulls latest changes)

Environment Variables

Variable	Description	Required
GIT_USERNAME	GitHub username	No (only for private repos)
GIT_TOKEN	GitHub Personal Access Token	No (only for private repos)

Creating a GitHub Personal Access Token

For private repositories, create a Personal Access Token:

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate new token (classic)
3. Select scopes: repo (Full control of private repositories)
4. Copy the token and use it as GIT_TOKEN

Project Structure

config-server/
├── src/
│   ├── main/
│   │   ├── java/com/example/configserver/
│   │   │   ├── ConfigServerApplication.java      # Main application class
│   │   │   ├── web/
│   │   │   │   └── ConfigAsYamlController.java   # Custom YAML endpoint
│   │   │   └── util/
│   │   │       └── PropertyTree.java             # Utility for nested maps
│   │   └── resources/
│   │       └── application.yml                   # Application configuration
│   └── test/
│       └── java/com/example/configserver/
│           ├── ConfigServerIT.java               # Integration tests
│           └── util/
│               └── PropertyTreeTest.java         # Unit tests
├── Dockerfile                                    # Multi-stage Docker build
├── pom.xml                                       # Maven configuration
└── README.md                                     # This file

Technology Stack

• Java: 21
• Spring Boot: 3.4.0
• Spring Cloud: 2024.0.0
• Build Tool: Maven
• Container: Docker with Eclipse Temurin

Troubleshooting

Configuration not found (404)

• Verify the configuration file exists in the Git repository
• Check directory structure: {service}/application-{env}.yaml
• Ensure the repository is accessible (check credentials for private repos)
• Check logs for Git clone/pull errors

Git authentication errors

• Verify GIT_USERNAME and GIT_TOKEN are set correctly
• Ensure the token has repo scope
• For public repositories, credentials are not required

Application fails to start

• Check if port 8080 is already in use
• Verify Git repository URL is accessible
• Check application logs for detailed error messages

Development

Build the project

./mvnw clean package

Run tests

./mvnw test

Skip tests during build

./mvnw package -DskipTests

License

This project is for internal use.