Spring Boot Boilerplate (Kotlin)

A production-ready Spring Boot 3.5.5 + Kotlin 2.0 starter project, offering a unified package with essential backend
features pre-integrated and real-world examples. Includes a complete OpenTelemetry-based observability stack for
unified monitoring, distributed tracing, and log aggregation.

Looking for a multi-module version? See kotlin-clean-architecture-multimodule for the Hexagonal Architecture + Multi-Module version of this project.

Table of Contents

• Quick Start
• Environment & Skills
• Project Guide
• Features
  • Security & Quality
  • Data Management
  • Integration & Messaging
  • Testing
  • Monitoring & Observability
• Service Access URLs

Quick Start

Prerequisites

• Java 21+
• Docker & Docker Compose

Run

# 1. Start infrastructure services
cd docker && ./setup.sh

# 2. Run application
./gradlew bootRun

Application is running at http://localhost:8085

See Service Access URLs for all available services.

Infrastructure services started by setup.sh:

• Kafka & Zookeeper
• Redis
• PostgreSQL & PgAdmin
• MailHog
• Prometheus
• Grafana
• Tempo
• Loki
• OpenTelemetry Collector

Environment & Skills

Application

Test

Infrastructure & Tooling

Monitoring & Observability

Project Guide

├── monitoring/                          # Observability configurations
├── docker/                              # Docker Compose files & setup script
└── src/
    ├── main/
    │   ├── kotlin/.../demo/
    │   │   ├── DemoApplication.kt       # Application entry point
    │   │   ├── common/                  # Shared utilities & base classes
    │   │   ├── post/                    # Post domain
    │   │   ├── user/                    # User domain
    │   │   ├── auth/                    # Auth domain
    │   │   ├── example/                 # Usage examples
    │   │   │   ├── UserDeleteConsumer   # Kafka Consumer (User Delete Event)
    │   │   │   └── WelcomeSignUpConsumer # Kafka Consumer (SignUp Event)
    │   │   ├── infrastructure/          # External integrations
    │   │   │   ├── kafka/
    │   │   │   ├── redis/
    │   │   │   ├── webhook/
    │   │   │   └── mail/
    │   │   ├── security/                # Spring Security + JWT
    │   │   └── utils/
    │   └── resources/
    │       ├── db/
    │       │   ├── migration/           # Flyway SQL scripts
    │       │   └── sql/                 # Spring Batch metadata SQL
    │       ├── logback-*.xml            # Logback configs (spring, prod, dev, local)
    │       ├── kotest.properties        # Kotest configuration
    │       └── application-*.yml        # Profile configs
    │           ├── common               # Shared variables
    │           ├── prod / dev / local   # Environment-specific
    │           ├── test                 # Test environment
    │           └── secret-{env}         # Secret variables per environment
    └── test/
        └── kotlin/.../demo/
            ├── common/                  # Shared test configuration
            ├── mockito/                 # Mockito-based tests
            └── kotest/                  # Kotest + MockK tests

Features

Security & Quality

CVE Management

• All dependency vulnerabilities centrally managed via applyCveFixes() in build.gradle.kts
• CVE fixes automatically applied during dependency resolution

// Example: CVE fix implementation
when {
    requested.group == "org.apache.commons" && requested.name == "commons-lang3" -> {
        useVersion("3.18.0")
        because("CVE-2025-48924")
    }
}

Code Quality

• Ktlint: Official lint rules
  • Report: build/reports/ktlint
• Detekt: Custom rules
  • Report: build/reports/detekt

Data Management

Database DDL

• Uses Flyway for DDL management instead of JPA auto-generation
• Migration scripts: src/main/resources/db/migration
• Alternative: JPA DDL auto-generation via application-common.yml

Spring Batch

• Metadata table required for all environments
• PostgreSQL schema: batch-postgresql-metadata-schema.sql
• Reference: Spring Batch Schema

Integration & Messaging

Webhook

• Configuration: application-common.yml (default enabled)
• Types: Slack, Discord

// 1. all
webHookProvider.sendAll(
	"Subscription request received from method ${parameter.method?.name}.",
	mutableListOf("Request Body: $body")
)

// 2. target slack
webHookProvider.sendSlack(
	"Failed to send message to Kafka (foo)",
	mutableListOf("Failed to send message to Kafka: ${exception.message} / $foo")
)

// 3. target discord
webHookProvider.sendDiscord(
	"Failed to send message to Kafka (bar)",
	mutableListOf("Failed to send message to Kafka: ${exception.message} / $bar")
)

Kafka

• Topic metadata: KafkaTopicMetaProvider
• DLQ: Dynamically created, default partition: 1

Email Testing

• MailHog integration (SMTP port 1025)
• Configuration: docker-compose.mailhog.yml, application-local.yml

Examples

• User signup → Email event via Kafka
  • Consumer: WelcomeSignUpConsumer
• User deletion after 1 year (Batch)
  • Consumer: UserDeleteConsumer

Testing

Mockito

• Base: BaseIntegrationController

Kotest & MockK

• Base: BaseIntegrationController
• Security bypass: SecurityListenerFactory

// Bypass Spring Security in tests
listeners(SecurityListenerFactory())

Then("Call DELETE /api/v1/users/{userId}").config(tags = setOf(SecurityListenerFactory.NonSecurityOption)) {
	// ...
}

Monitoring & Observability

OpenTelemetry Stack

• All metrics, traces, logs collected via OpenTelemetry Collector
• Collector endpoints:
  • OTLP gRPC: localhost:4317
  • OTLP HTTP: localhost:4318

Configuration

• OpenTelemetry Collector
• Prometheus
• Tempo
• Loki

Service Access URLs

Application

Infrastructure

Observability

Grafana Data Sources (Docker internal network):

• Prometheus: http://prometheus:9090
• Tempo: http://tempo:3200
• Loki: http://loki:3100

Author

Hyunwoo Park