[Ktor] Ktor 프레임워크 서버 환경 변수 설정하기 - yml, hocon

개요

Ktor 프로젝트에서는 호스트 주소, 포트 번호, 모듈 등과 같은 서버 환경 변수를 다양한 방법으로 구성할 수 있다. 스프링 프로젝트에서는 서버 환경 변수를 properties 또는 yml 파일로 구성하는 반면에 Ktor 프로젝트는 서버 환경 변수를 애플리케이션 내에서 코틀린 코드로 구성하는 방법과, 스프링 프로젝트와 유사한 파일로 구성하는 방법으로 구분된다.

코트로 서버 환경 변수를 설정하는 방법보다 yml과 같은 파일로 서버 환경 변수를 구성하는 것이 친숙하기 때문에 파일로 환경 변수를 구성하는 방법을 알아보고자 한다.

 

 

의존성 추가

Ktor에서는 파일로 서버 환경 변수를 구성할 때 YMAL(.yml 또는 .ymal) 파일과 HOCON(.conf) 파일로 구성할 수 있다. 만약, yml 파일로 서버 환경 변수를 구성하고자 한다면 Ktor 프로젝트 내에 의존성을 추가해야 한다.

dependencies {
    ...
    implementation("io.ktor:ktor-server-config-yaml:$ktor_version")
    ...
}

• Ktor 프로젝트 생성할 때, Configuration in 설정을 YMAL로 설정하면 해당 의존성이 자동으로 추가된다.
• HOCON 파일로 서버 환경 변수를 구성할 때는 기본으로 제공되어 별도의 의존성을 추가하지 않아도 된다.

 

 

기본 구성

Ktor 프로젝트를 생성하면 기본적으로 다음과 같이 구성된다.

application.yml

ktor:
  deployment:
    port: 8080
  application:
    modules:
      - com.example.ApplicationKt.module

• 스프링 프로젝트의 application.yml 파일과 상당히 유사하다.

 

application.conf

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

• HOCON 파일 또한 yml 파일과 크게 다른 구조는 아니지만 yml 파일의 키(key)와 값(value)을 구분하는 콜론(:)이 아닌 중괄호({})를 통해 계층을 표현한다.

 

위 설정 파일들은 ktor 프로젝트의 서버 포트 설정과 애플리케이션에 구성된 모듈을 불러올 패키지 경로를 지정하고 있다.

Application.kt

com.example.ApplicationKt.module은 아래의 Application.module() 함수를 호출한다.

package com.example

import io.ktor.server.application.*
import com.example.plugins.*

fun main(args: Array<String>): Unit =
    io.ktor.server.netty.EngineMain.main(args)

fun Application.module() {
    configureRouting()
    configureSerialization()
    configureKoin()
    ...
}

• Application.module() 함수에는 애플리케이션에 사용할 외부 라이브러리, 파일에 사전 정의된 서버 환경 변수(호스트, 포트, SSL 설정 등), 사용자 정의 환경 변수 등을 포함하여 서버 설정을 구성할 수 있다.
• 클라이언트의 요청을 처리하는 Routing 플러그인, 직렬화/역직렬화를 처리하는 Serialization 플러그인, Kotlin 의존성 주입 라이브러리 Koin 등이 포함되어 있는 코드다.

 

 

Ktor에서 제공하는 기본 속성

다음은 ktor에서 미리 정의하여 기본적으로 제공하는 설정 목록이다.

 

ktor.deployment.host

애플리케이션의 호스트 주소를 설정하는 것으로 localhost, 127.0.0.1 등과 같이 주소를 설정할 수 있다. 실제 서버 환경에서는 외부 IP 주소나 도메인 이름을 설정한다.

이 설정을 통해 ktor 애플리케이션은 특정 주소나 인터페이스에 바인딩되어 해당 위치로 들어오는 요청을 수신할 수 있다.

 

ktor.deployment.port

애플리케이션 서버의 포트를 설정하는 것으로 앞의 예시와 같다. 8080, 3306 등의 포트를 설정하여 클라이언트 요청을 처리하는 데 사용할 포트를 지정한다.

ktor:
  deployment:
    host = "0.0.0.0"  # 호스트 주소
    port = 8080       # 포트 번호

 

ktor.deployment.sslPort

주로 HTTPS 통신 설정을 위한 속성으로 SSL 수신 포트를 설정할 수 있다. 예) 8443, 443(HTTPS 포트)

만약, sslPort를 설정한 경우 다음 SSL 관련 속성을 추가로 지정해야 한다.

• ktor.security.ssl.keyStore : SSL 키 스토어 파일의 경로 지정
• ktor.security.ssl.keyAlias : 키 스토어에서 사용할 인증서 및 개인 키의 별칭 지정
• ktor.security.ssl.keyStorePassword : SSL 키 스토어의 암호 설정
• ktor.security.ssl.privateKeyPassword : SSL 개인 키 암호 설정

ktor:
  deployment:
    sslPort: 8443
	security:
    ssl:
      keyStore: keystore.jks
      keyAlias: sampleAlias
      keyStorePassword: foobar
      privateKeyPassword: foobar

 

ktor.deployment.watch

개발 모드로 실행된 애플리케이션의 지정된 범위에서 코드 변경을 감지하여 자동으로 애플리케이션을 재실행한다.

ktor:
  development: true
  deployment:
    watch:
      - classes

 

ktor.deployment.rootPath

애플리케이션의 서블릿 컨텍스트 경로를 설정할 수 있다. 만약 rootPath를 “/myapp”으로 설정하면 애플리케이션의 모든 URL 경로는 /myapp 아래에서 시작하게 된다.

ktor:
  deployment:
    host: "0.0.0.0"
    port: 8080
    rootPath: "/myapp"

 

ktor.deployment.shutdown.url

애플리케이션을 종료하기 위한 URL을 지정할 수 있다. URL 엔드포인트에 GET 요청을 보내면 Graceful Shutdown을 수행하고 애플리케이션이 종료된다.

Graceful Shutdown은 현재 처리 중인 요청을 완료하고, 새로운 요청을 수락하지 않은 방식으로 종료하는 것을 말한다.

ktor:
  deployment:
    host: "127.0.0.1"
    port: 8080
    shutdown:
      url: "/shutdown"

http://127.0.0.1:8080/shotdown에 GET 요청을 보내면 애플리케이션을 종료할 수 있게 된다.

 

 

환경 변수 설정

구성 파일에서 ${ENV} / $ENV와 같은 구문을 사용하여 매개변수를 환경 변수로 대체할 수 있다.

application.yml

ktor:
  deployment:
    port: $PORT

---

ktor:
  deployment:
    port: "$PORT:8080"

 

application.conf

ktor {
    deployment {
        port = ${PORT}
    }
}

---

ktor {
    deployment {
        port = 8080
        port = ${?PORT}
    }
}