파일 기반 설정

파일 기반 설정

Ktor를 사용하면 호스트 주소 및 포트, 로드할

모듈

모듈을 사용하면 라우트를 그룹화하여 애플리케이션을 구조화할 수 있습니다.

등 다양한 서버 파라미터를 설정할 수 있습니다. 설정 방식은 서버를 생성할 때 사용한 방법(

embeddedServer 또는 EngineMain

애플리케이션 배포 요구 사항에 따라 서버를 생성하는 방법을 알아봅니다.

)에 따라 달라집니다.

EngineMain의 경우, Ktor는 HOCON 또는 YAML 형식을 사용하는 설정 파일에서 설정을 로드합니다. 이 방식은 서버 설정에 더 큰 유연성을 제공하며, 애플리케이션을 다시 컴파일하지 않고도 설정을 변경할 수 있게 해줍니다. 또한, 커맨드 라인에서 애플리케이션을 실행하면서 해당 커맨드 라인 인자를 전달하여 필요한 서버 파라미터를 오버라이드할 수 있습니다.

개요

EngineMain 을 사용하여 서버를 시작하면, Ktor는 resources 디렉토리에 있는 application.* 파일에서 설정 정보를 자동으로 로드합니다. 두 가지 설정 형식이 지원됩니다:

• HOCON ( application.conf )

• YAML ( application.yaml )

  NOTE

  YAML 설정 파일을 사용하려면 ktor-server-config-yaml

  의존성

  기존 Gradle/Maven 프로젝트에 Ktor 서버 의존성을 추가하는 방법을 알아봅니다.

  을 추가해야 합니다.

  YAML 설정은 현재 Maven 기반 Ktor 프로젝트에서 지원되지 않습니다.

설정 파일에는 최소한 ktor.application.modules 속성을 사용하여 지정된

로드할 모듈

모듈을 사용하면 라우트를 그룹화하여 애플리케이션을 구조화할 수 있습니다.

이 포함되어야 합니다. 예시:

application.confapplication.yaml

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

로드할 모듈 외에도 사전 정의된 속성(포트 또는 호스트, SSL 설정 등) 및 사용자 정의 설정을 포함한 다양한 서버 설정을 구성할 수 있습니다. 몇 가지 예시를 살펴보겠습니다.

기본 설정

아래 예시에서는 ktor.deployment.port 속성을 사용하여 서버 수신 포트를 8080으로 설정합니다.

application.confapplication.yaml

엔진 설정

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

application.confapplication.yaml

Netty

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

application.confapplication.yaml

SSL 설정

아래 예시는 Ktor가 8443 SSL 포트에서 수신 대기하도록 설정하고, 별도의 security 블록에 필요한

SSL 설정

필수 의존성: io.ktor:ktor-network-tls-certificates 코드 예시: ssl-engine-main, ssl-embedded-server

을 지정합니다.

application.confapplication.yaml

사용자 정의 설정

Ktor는 사전 정의된 속성 외에도 설정 파일에 사용자 정의 설정을 유지할 수 있도록 허용합니다. 아래 설정 파일에는 JWT 설정을 보관하는 데 사용되는 사용자 정의 jwt 그룹이 포함되어 있습니다.

application.confapplication.yaml

코드에서 이러한 설정을 읽고 처리할 수 있습니다.

비밀 키(secret key), 데이터베이스 연결 설정 등과 같은 민감한 데이터는 설정 파일에 평문으로 저장해서는 안 됩니다. 이러한 파라미터를 지정하려면 환경 변수 를 사용하는 것이 좋습니다.

사전 정의된 속성

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

ktor.deployment.host

호스트 주소.

예시 : 0.0.0.0

ktor.deployment.port

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

예시 : 8080, 0

ktor.deployment.sslPort

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

예시 : 8443, 0

NOTE

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

ktor.deployment.watch

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

ktor.deployment.rootPath

서블릿

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

컨텍스트 경로.

예시 : /

ktor.deployment.shutdown.url

셧다운(shutdown) URL. 이 옵션은

Shutdown URL

코드 예시: %example_name%

플러그인을 사용합니다.

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 코드 예시: ssl-engine-main, ssl-embedded-server

속성을 지정해야 합니다:

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 속성에 할당할 수 있습니다:

application.confapplication.yaml

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

application.confapplication.yaml

코드에서 설정 읽기

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

application.confapplication.yaml

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

설정을 데이터 클래스로 역직렬화하기

설정 값을 타입 세이프(type-safe)하게 사용하기 위해 설정을 Kotlin 클래스로 역직렬화할 수 있습니다.

아래 예시에서는 app 및 security 설정 섹션을 정의하고 이를 직렬화 가능한 Kotlin 데이터 클래스에 매핑합니다.

application.confapplication.yaml

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

전체 ApplicationConfig를 역직렬화해야 하는 경우, ApplicationConfig.getAs() 함수를 사용합니다:

커맨드 라인

EngineMain을 사용하여 서버를 생성하는 경우,

패키징된 애플리케이션

Ktor Gradle 플러그인을 사용하여 실행 가능한 fat JAR를 생성하고 실행하는 방법을 알아봅니다.

을 커맨드 라인에서 실행하고 해당 커맨드 라인 인자를 전달하여 필요한 서버 파라미터를 오버라이드할 수 있습니다. 예를 들어, 다음과 같은 방법으로 설정 파일에 지정된 포트를 오버라이드할 수 있습니다:

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

-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 코드 예시: ssl-engine-main, ssl-embedded-server

옵션:

-sslPort

SSL 수신 포트.

-sslKeyStore

SSL 키 스토어.

해당하는 커맨드 라인 옵션이 없는 사전 정의된 속성을 오버라이드해야 하는 경우, 다음과 같이 -P 플래그를 사용합니다:

-P 플래그를 사용하여 사용자 정의 속성을 오버라이드할 수도 있습니다.

예시: 사용자 정의 속성을 사용하여 환경 지정

로컬 개발 또는 운영 환경과 같이 서버가 실행 중인 환경에 따라 애플리케이션 동작을 변경하기 위해 사용자 정의 설정 속성을 사용할 수 있습니다.

이를 위해 application.conf 또는 application.yaml에 사용자 정의 속성을 정의하고 환경 변수로부터 값을 할당합니다. 아래 예시에서는 KTOR_ENV 환경 변수가 사용자 정의 ktor.environment 속성에 할당됩니다. 그러면 KTOR_ENV의 값을 로컬 환경과 운영 환경에 대해 다르게 설정할 수 있습니다.

application.confapplication.yaml

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

전체 코드 예시는 engine-main-custom-environment 를 참조하세요.