파일 기반 설정
Ktor를 사용하면 호스트 주소 및 포트, 로드할 모듈모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다. 등 다양한 서버 파라미터를 설정할 수 있습니다. 설정 방식은 서버를 생성할 때 사용한 방법( embeddedServer 또는 EngineMain 애플리케이션 배포 요구 사항에 따라 서버를 생성하는 방법을 알아봅니다.)에 따라 달라집니다.
EngineMain의 경우, Ktor는 HOCON 또는 YAML 형식을 사용하는 설정 파일에서 설정을 로드합니다. 이 방식은 서버 설정에 더 큰 유연성을 제공하며, 애플리케이션을 다시 컴파일하지 않고도 설정을 변경할 수 있게 해줍니다. 또한, 커맨드 라인에서 애플리케이션을 실행하면서 해당 커맨드 라인 인자를 전달하여 필요한 서버 파라미터를 오버라이드할 수 있습니다.
개요
EngineMain 을 사용하여 서버를 시작하면, Ktor는 resources 디렉토리에 있는 application.* 파일에서 설정 정보를 자동으로 로드합니다. 두 가지 설정 형식이 지원됩니다:
HOCON ( application.conf )
YAML ( application.yaml )
YAML 설정 파일을 사용하려면
ktor-server-config-yaml의존성 기존 Gradle/Maven 프로젝트에 Ktor 서버 의존성을 추가하는 방법을 알아봅니다. 을 추가해야 합니다.YAML 설정은 현재 Maven 기반 Ktor 프로젝트에서 지원되지 않습니다.
설정 파일에는 최소한 ktor.application.modules 속성을 사용하여 지정된 로드할 모듈 모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다. 이 포함되어야 합니다. 예시:
ktor {
application {
modules = [ com.example.ApplicationKt.module ]
}
}ktor:
application:
modules:
- com.example.ApplicationKt.module 이 경우, Ktor는 아래 Application.kt 파일에 있는 Application.module 함수를 호출합니다:
package com.example
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)
fun Application.module() {
routing {
get("/") {
call.respondText("Hello, world!")
}
}
}로드할 모듈 외에도 사전 정의된 속성(포트 또는 호스트, SSL 설정 등) 및 사용자 정의 설정을 포함한 다양한 서버 설정을 구성할 수 있습니다. 몇 가지 예시를 살펴보겠습니다.
기본 설정
아래 예시에서는 ktor.deployment.port 속성을 사용하여 서버 수신 포트를 8080으로 설정합니다.
ktor {
deployment {
port = 8080
}
application {
modules = [ com.example.ApplicationKt.module ]
}
}ktor:
deployment:
port: 8080
application:
modules:
- com.example.ApplicationKt.module엔진 설정
EngineMain을 사용하는 경우, ktor.deployment 그룹 내에 모든 엔진에 공통적인 옵션을 지정할 수 있습니다.
ktor {
deployment {
connectionGroupSize = 2
workerGroupSize = 5
callGroupSize = 10
shutdownGracePeriod = 2000
shutdownTimeout = 3000
}
}ktor:
deployment:
connectionGroupSize: 2
workerGroupSize: 5
callGroupSize: 10
shutdownGracePeriod: 2000
shutdownTimeout: 3000SSL 설정
아래 예시는 Ktor가 8443 SSL 포트에서 수신 대기하도록 설정하고, 별도의 security 블록에 필요한 SSL 설정 필수 의존성: io.ktor:ktor-network-tls-certificates 을 지정합니다.
ktor {
deployment {
port = 8080
sslPort = 8443
}
application {
modules = [ com.example.ApplicationKt.module ]
}
security {
ssl {
keyStore = keystore.jks
keyAlias = sampleAlias
keyStorePassword = foobar
privateKeyPassword = foobar
trustStore = truststore.jks
trustStorePassword = foobar
enabledProtocols = ["TLSv1.2", "TLSv1.3"]
}
}
}ktor:
deployment:
port: 8080
sslPort: 8443
application:
modules:
- com.example.ApplicationKt.module
security:
ssl:
keyStore: keystore.jks
keyAlias: sampleAlias
keyStorePassword: foobar
privateKeyPassword: foobar
trustStore: truststore.jks
trustStorePassword: foobar
enabledProtocols: ["TLSv1.2", "TLSv1.3"]사용자 정의 설정
Ktor는 사전 정의된 속성 외에도 설정 파일에 사용자 정의 설정을 유지할 수 있도록 허용합니다. 아래 설정 파일에는 JWT 설정을 보관하는 데 사용되는 사용자 정의 jwt 그룹이 포함되어 있습니다.
ktor {
deployment {
port = 8080
}
application {
modules = [ com.example.ApplicationKt.main ]
}
}
jwt {
secret = "secret"
issuer = "http://0.0.0.0:8080/"
audience = "http://0.0.0.0:8080/hello"
realm = "Access to 'hello'"
}ktor:
deployment:
port: 8080
application:
modules:
- com.example.ApplicationKt.main
jwt:
secret: "secret"
issuer: "http://0.0.0.0:8080/"
audience: "http://0.0.0.0:8080/hello"
realm: "Access to 'hello'"코드에서 이러한 설정을 읽고 처리할 수 있습니다.
비밀 키(secret key), 데이터베이스 연결 설정 등과 같은 민감한 데이터는 설정 파일에 평문으로 저장해서는 안 됩니다. 이러한 파라미터를 지정하려면 환경 변수 를 사용하는 것이 좋습니다.
사전 정의된 속성
다음은 설정 파일 내부에서 사용할 수 있는 사전 정의된 설정 목록입니다.
호스트 주소.
예시 : 0.0.0.0
수신 포트. 서버를 랜덤 포트에서 실행하려면 이 속성을 0으로 설정할 수 있습니다.
예시 : 8080, 0
SSL 수신 포트. 서버를 랜덤 포트에서 실행하려면 이 속성을 0으로 설정할 수 있습니다.
예시 : 8443, 0
SSL에는 아래에 나열된 추가 옵션이 필요합니다.
자동 리로딩(auto-reloading)에 사용되는 감시 경로.
서블릿WAR 아카이브를 사용하여 서블릿 컨테이너 내에서 Ktor 애플리케이션을 실행하고 배포하는 방법을 알아봅니다. 컨텍스트 경로.
예시 : /
셧다운(shutdown) URL. 이 옵션은 Shutdown URL코드 예제: shutdown-url 플러그인을 사용합니다.
서버가 새로운 요청 수락을 중단하기까지의 최대 시간(밀리초).
서버가 완전히 중단될 때까지 기다리는 최대 시간(밀리초).
애플리케이션 호출을 처리하는 데 사용되는 스레드 풀의 최소 크기.
새로운 연결을 수락하고 호출 처리를 시작하는 데 사용되는 스레드 수.
연결 처리, 메시지 파싱 및 엔진의 내부 작업을 수행하기 위한 이벤트 그룹의 크기.
ktor.deployment.sslPort를 설정한 경우, 다음과 같은 SSL 관련 필수 의존성: io.ktor:ktor-network-tls-certificates 속성을 지정해야 합니다:
SSL 키 스토어.
SSL 키 스토어의 에일리어스(alias).
SSL 키 스토어의 비밀번호.
SSL 개인 키의 비밀번호.
환경 변수
설정 파일에서 파라미터를 환경 변수로 대체할 수 있습니다.
- HOCON (application.conf)에서는
${ENV}구문만 지원됩니다. - YAML (application.yaml)에서는
${ENV}및$ENV구문이 모두 지원됩니다.
예를 들어, 다음과 같은 방법으로 PORT 환경 변수를 ktor.deployment.port 속성에 할당할 수 있습니다:
ktor {
deployment {
port = ${PORT}
}
}ktor:
deployment:
port: ${PORT} # or $PORT 이 경우 환경 변수 값이 수신 포트를 지정하는 데 사용됩니다. 런타임에 PORT 환경 변수가 존재하지 않는 경우, 다음과 같이 기본 포트 값을 제공할 수 있습니다:
ktor {
deployment {
port = 8080
port = ${?PORT}
}
}ktor:
deployment:
port: ${PORT:8080} # or "$PORT:8080"코드에서 설정 읽기
Ktor를 사용하면 애플리케이션 코드에서 설정 파일에 지정된 속성값에 액세스할 수 있습니다. 다음 예시에서는 ktor.deployment.port 속성을 지정했습니다:
ktor {
deployment {
port = 8080
}
}ktor:
deployment:
port: 8080ApplicationEnvironment.config() 함수를 사용하여 애플리케이션의 설정에 액세스하고 속성값을 가져올 수 있습니다. 필요한 값에 액세스하려면 .property() 함수를 사용하고, 선택적 값의 경우 .propertyOrNull()을 사용합니다:
fun Application.module() {
val port = environment.config.propertyOrNull("ktor.deployment.port")?.getString() ?: "8080"
routing {
get {
call.respondText("Listening on port $port")
}
}
}설정을 데이터 클래스로 역직렬화하기
설정 값을 타입 세이프(type-safe)하게 사용하기 위해 설정을 Kotlin 클래스로 역직렬화할 수 있습니다.
아래 예시에서는 app 및 security 설정 섹션을 정의하고 이를 직렬화 가능한 Kotlin 데이터 클래스에 매핑합니다.
app {
port = 8080
host = "0.0.0.0"
}
security {
clientId = ${?CLIENT_ID}
clientSecret = ${?CLIENT_SECRET}
}app:
port: 8080
host: "0.0.0.0"
security:
clientId: $CLIENT_ID
clientSecret: $CLIENT_SECRET 특정 설정 섹션을 역직렬화하려면 Application.property() 또는 Application.propertyOrNull() 함수를 사용합니다:
@Serializable
data class Security(val clientId: String, val clientSecret: String)
fun Application.module() {
val securityConfig: Security = property("security")
println("Authorization header: ${securityConfig.clientId}:${securityConfig.clientSecret}")
} 전체 ApplicationConfig를 역직렬화해야 하는 경우, ApplicationConfig.getAs() 함수를 사용합니다:
@Serializable
data class App(val port: Int, val host: String)
@Serializable
data class Security(val clientId: String, val clientSecret: String)
@Serializable
data class Config(val app: App, val security: Security)
fun Application.module() {
val config = environment.config.getAs<Config>()
val clientId = config.security.clientId
val clientSecret = config.security.clientSecret
println("Authorization header: $clientId:$clientSecret")
}커맨드 라인
EngineMain을 사용하여 서버를 생성하는 경우, 패키징된 애플리케이션Ktor Gradle 플러그인을 사용하여 실행 가능한 fat JAR를 생성하고 실행하는 방법을 알아봅니다.을 커맨드 라인에서 실행하고 해당 커맨드 라인 인자를 전달하여 필요한 서버 파라미터를 오버라이드할 수 있습니다. 예를 들어, 다음과 같은 방법으로 설정 파일에 지정된 포트를 오버라이드할 수 있습니다:
java -jar sample-app.jar -port=8080사용 가능한 커맨드 라인 옵션은 다음과 같습니다:
JAR 파일 경로.
resources에 있는 application.conf / application.yaml 대신 사용할 사용자 정의 설정 파일의 경로.
예시 : java -jar sample-app.jar -config=anotherfile.conf
참고 : 여러 값을 전달할 수 있습니다. java -jar sample-app.jar -config=config-base.conf -config=config-dev.conf. 이 경우 모든 설정이 병합되며, 오른쪽에 있는 설정 파일의 값이 우선순위를 갖습니다.
호스트 주소.
수신 포트.
자동 리로딩(auto-reloading)에 사용되는 감시 경로.
SSL 관련필수 의존성: io.ktor:ktor-network-tls-certificates 옵션:
SSL 수신 포트.
SSL 키 스토어.
해당하는 커맨드 라인 옵션이 없는 사전 정의된 속성을 오버라이드해야 하는 경우, 다음과 같이 -P 플래그를 사용합니다:
java -jar sample-app.jar -P:ktor.deployment.callGroupSize=7-P 플래그를 사용하여 사용자 정의 속성을 오버라이드할 수도 있습니다.
예시: 사용자 정의 속성을 사용하여 환경 지정
로컬 개발 또는 운영 환경과 같이 서버가 실행 중인 환경에 따라 애플리케이션 동작을 변경하기 위해 사용자 정의 설정 속성을 사용할 수 있습니다.
이를 위해 application.conf 또는 application.yaml에 사용자 정의 속성을 정의하고 환경 변수로부터 값을 할당합니다. 아래 예시에서는 KTOR_ENV 환경 변수가 사용자 정의 ktor.environment 속성에 할당됩니다. 그러면 KTOR_ENV의 값을 로컬 환경과 운영 환경에 대해 다르게 설정할 수 있습니다.
ktor {
environment = ${?KTOR_ENV}
}ktor:
environment: $?KTOR_ENV 런타임에 코드에서 설정을 읽어 ktor.environment 값에 액세스하고 필요한 작업을 수행할 수 있습니다:
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
fun Application.module() {
val env = environment.config.propertyOrNull("ktor.environment")?.getString()
routing {
get {
call.respondText(when (env) {
"dev" -> "Development"
"prod" -> "Production"
else -> "..."
})
}
}
}전체 코드 예시는 engine-main-custom-environment 를 참조하세요.
