Skip to content

파일 기반 설정

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 속성을 사용하여 지정된 로드할 모듈 모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다. 이 포함되어야 합니다. 예시:

shell
ktor {
    application {
        modules = [ com.example.ApplicationKt.module ]
    }
}
yaml
ktor:
    application:
        modules:
            - com.example.ApplicationKt.module

이 경우, Ktor는 아래 Application.kt 파일에 있는 Application.module 함수를 호출합니다:

kotlin
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으로 설정합니다.

shell
ktor {
    deployment {
        port = 8080
    }
    application {
        modules = [ com.example.ApplicationKt.module ]
    }
}
yaml
ktor:
    deployment:
        port: 8080
    application:
        modules:
            - com.example.ApplicationKt.module

엔진 설정

EngineMain을 사용하는 경우, ktor.deployment 그룹 내에 모든 엔진에 공통적인 옵션을 지정할 수 있습니다.

shell
ktor {
    deployment {
        connectionGroupSize = 2
        workerGroupSize = 5
        callGroupSize = 10
        shutdownGracePeriod = 2000
        shutdownTimeout = 3000
    }
}
yaml
ktor:
    deployment:
        connectionGroupSize: 2
        workerGroupSize: 5
        callGroupSize: 10
        shutdownGracePeriod: 2000
        shutdownTimeout: 3000

Netty

설정 파일의 ktor.deployment 그룹 내에서 Netty 전용 옵션을 구성할 수도 있습니다:

shell
ktor {
    deployment {
        maxInitialLineLength = 2048
        maxHeaderSize = 1024
        maxChunkSize = 42
    }
}
yaml
ktor:
    deployment:
        maxInitialLineLength: 2048
        maxHeaderSize: 1024
        maxChunkSize: 42

SSL 설정

아래 예시는 Ktor가 8443 SSL 포트에서 수신 대기하도록 설정하고, 별도의 security 블록에 필요한 SSL 설정 필수 의존성: io.ktor:ktor-network-tls-certificates 을 지정합니다.

shell
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"]
        }
    }
}
yaml
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 그룹이 포함되어 있습니다.

shell
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'"
}
yaml
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), 데이터베이스 연결 설정 등과 같은 민감한 데이터는 설정 파일에 평문으로 저장해서는 안 됩니다. 이러한 파라미터를 지정하려면 환경 변수 를 사용하는 것이 좋습니다.

사전 정의된 속성

다음은 설정 파일 내부에서 사용할 수 있는 사전 정의된 설정 목록입니다.

ktor.deployment.host

호스트 주소.

예시 : 0.0.0.0

ktor.deployment.port

수신 포트. 서버를 랜덤 포트에서 실행하려면 이 속성을 0으로 설정할 수 있습니다.

예시 : 8080, 0

ktor.deployment.sslPort

SSL 수신 포트. 서버를 랜덤 포트에서 실행하려면 이 속성을 0으로 설정할 수 있습니다.

예시 : 8443, 0

SSL에는 아래에 나열된 추가 옵션이 필요합니다.

ktor.deployment.watch

자동 리로딩(auto-reloading)에 사용되는 감시 경로.

ktor.deployment.rootPath

서블릿WAR 아카이브를 사용하여 서블릿 컨테이너 내에서 Ktor 애플리케이션을 실행하고 배포하는 방법을 알아봅니다. 컨텍스트 경로.

예시 : /

ktor.deployment.shutdown.url

셧다운(shutdown) URL. 이 옵션은 Shutdown URL코드 예제: shutdown-url 플러그인을 사용합니다.

ktor.deployment.shutdownGracePeriod

서버가 새로운 요청 수락을 중단하기까지의 최대 시간(밀리초).

ktor.deployment.shutdownTimeout

서버가 완전히 중단될 때까지 기다리는 최대 시간(밀리초).

ktor.deployment.callGroupSize

애플리케이션 호출을 처리하는 데 사용되는 스레드 풀의 최소 크기.

ktor.deployment.connectionGroupSize

새로운 연결을 수락하고 호출 처리를 시작하는 데 사용되는 스레드 수.

ktor.deployment.workerGroupSize

연결 처리, 메시지 파싱 및 엔진의 내부 작업을 수행하기 위한 이벤트 그룹의 크기.

ktor.deployment.sslPort를 설정한 경우, 다음과 같은 SSL 관련 필수 의존성: io.ktor:ktor-network-tls-certificates 속성을 지정해야 합니다:

ktor.security.ssl.keyStore

SSL 키 스토어.

ktor.security.ssl.keyAlias

SSL 키 스토어의 에일리어스(alias).

ktor.security.ssl.keyStorePassword

SSL 키 스토어의 비밀번호.

ktor.security.ssl.privateKeyPassword

SSL 개인 키의 비밀번호.

환경 변수

설정 파일에서 파라미터를 환경 변수로 대체할 수 있습니다.

  • HOCON (application.conf)에서는 ${ENV} 구문만 지원됩니다.
  • YAML (application.yaml)에서는 ${ENV} 및 $ENV 구문이 모두 지원됩니다.

예를 들어, 다음과 같은 방법으로 PORT 환경 변수를 ktor.deployment.port 속성에 할당할 수 있습니다:

shell
ktor {
    deployment {
        port = ${PORT}
    }
}
yaml
ktor:
    deployment:
        port: ${PORT} # or $PORT

이 경우 환경 변수 값이 수신 포트를 지정하는 데 사용됩니다. 런타임에 PORT 환경 변수가 존재하지 않는 경우, 다음과 같이 기본 포트 값을 제공할 수 있습니다:

shell
ktor {
    deployment {
        port = 8080
        port = ${?PORT}
    }
}
yaml
ktor:
    deployment:
        port: ${PORT:8080} # or "$PORT:8080"

코드에서 설정 읽기

Ktor를 사용하면 애플리케이션 코드에서 설정 파일에 지정된 속성값에 액세스할 수 있습니다. 다음 예시에서는 ktor.deployment.port 속성을 지정했습니다:

shell
ktor {
    deployment {
        port = 8080
    }
}
yaml
ktor:
    deployment:
        port: 8080

ApplicationEnvironment.config() 함수를 사용하여 애플리케이션의 설정에 액세스하고 속성값을 가져올 수 있습니다. 필요한 값에 액세스하려면 .property() 함수를 사용하고, 선택적 값의 경우 .propertyOrNull()을 사용합니다:

kotlin
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 데이터 클래스에 매핑합니다.

shell
app {
    port = 8080
    host = "0.0.0.0"
}

security {
    clientId = ${?CLIENT_ID}
    clientSecret = ${?CLIENT_SECRET}
}
yaml
app:
    port: 8080
    host: "0.0.0.0"
security:
    clientId: $CLIENT_ID
    clientSecret: $CLIENT_SECRET

특정 설정 섹션을 역직렬화하려면 Application.property() 또는 Application.propertyOrNull() 함수를 사용합니다:

kotlin
@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() 함수를 사용합니다:

kotlin
@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를 생성하고 실행하는 방법을 알아봅니다.을 커맨드 라인에서 실행하고 해당 커맨드 라인 인자를 전달하여 필요한 서버 파라미터를 오버라이드할 수 있습니다. 예를 들어, 다음과 같은 방법으로 설정 파일에 지정된 포트를 오버라이드할 수 있습니다:

shell
java -jar sample-app.jar -port=8080

사용 가능한 커맨드 라인 옵션은 다음과 같습니다:

-jar

JAR 파일 경로.

-config

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. 이 경우 모든 설정이 병합되며, 오른쪽에 있는 설정 파일의 값이 우선순위를 갖습니다.

-host

호스트 주소.

-port

수신 포트.

-watch

자동 리로딩(auto-reloading)에 사용되는 감시 경로.

SSL 관련필수 의존성: io.ktor:ktor-network-tls-certificates 옵션:

-sslPort

SSL 수신 포트.

-sslKeyStore

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}
}
yaml
ktor:
    environment: $?KTOR_ENV

런타임에 코드에서 설정을 읽어 ktor.environment 값에 액세스하고 필요한 작업을 수행할 수 있습니다:

kotlin
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 를 참조하세요.