Skip to content

Docker ​

このセクションでは、Ktor Gradle プラグインを使用して、Docker でアプリケーションをパッケージ化、実行、デプロイする方法について説明します。

Ktor プラグインのインストール ​

kotlin
plugins {
    alias(ktorLibs.plugins.ktor)
}
groovy
plugins {
    alias(ktorLibs.plugins.ktor)
}
上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。

Ktor Gradle プラグインを Kotlin Multiplatform Gradle プラグインと一緒に適用した場合、Docker 連携は自動的に無効化されます。 これらを併用するには、以下の手順を実行してください。

  1. 上記のように Ktor Gradle プラグインを適用した JVM 専用プロジェクトを作成します。
  2. その JVM 専用プロジェクトに、Kotlin Multiplatform プロジェクトを依存関係として追加します。

この回避策で問題が解決しない場合は、KTOR-8464 にコメントを残してお知らせください。

プラグインタスク ​

プラグインをインストールすると、アプリケーションのパッケージ化、実行、デプロイを行うための以下のタスクが利用可能になります。

  • buildImage: プロジェクトの Docker イメージを tarball にビルドします。このタスクは build ディレクトリに jib-image.tar ファイルを生成します。docker load コマンドを使用して、このイメージを Docker デーモンに読み込むことができます。
    Bash
    docker load < build/jib-image.tar
  • publishImageToLocalRegistry: プロジェクトの Docker イメージをビルドし、ローカルレジストリに公開します。
  • runDocker: プロジェクトのイメージをビルドして Docker デーモンに読み込み、実行します。このタスクを実行すると Ktor サーバーが起動し、デフォルトでは http://0.0.0.0:8080 で応答します。サーバーが別のポートを使用するように構成されている場合は、ポートマッピングを調整できます。
  • publishImage: プロジェクトの Docker イメージをビルドし、Docker Hub や Google Container Registry などの外部レジストリに公開します。このタスクを使用するには、ktor.docker.externalRegistry プロパティを使用して外部レジストリを設定する必要がある点に注意してください。

デフォルトでは、これらのタスクは ktor-docker-image という名前と latest タグでイメージをビルドします。プラグイン設定でこれらの値をカスタマイズできます。

Ktor プラグインの設定 ​

Docker タスクに関連する Ktor プラグインの設定を行うには、build.gradle.(kts) ファイルで ktor.docker エクステンションを使用します。

kotlin
ktor {
    docker {
        // ...
    }
}

JRE バージョン ​

jreVersion プロパティは、イメージ内で使用する JRE バージョンを指定します。

kotlin
ktor {
    docker {
        jreVersion.set(JavaVersion.VERSION_17)
    }
}

イメージ名とタグ ​

イメージ名とタグをカスタマイズする必要がある場合は、それぞれ localImageName プロパティと imageTag プロパティを使用します。

kotlin
ktor {
    docker {
        localImageName.set("sample-docker-image")
        imageTag.set("0.0.1-preview")
    }
}

ポートマッピング ​

デフォルトでは、runDocker タスクはコンテナのポート 8080 を Docker ホストのポート 8080 に公開します。 必要に応じて、portMappings プロパティを使用してこれらのポートを変更できます。 これは、サーバーが別のポートを使用するように設定されている場合に役立ちます。

以下の例は、コンテナのポート 8080 を Docker ホストのポート 80 にマッピングする方法を示しています。

kotlin
ktor {
    docker {
        portMappings.set(listOf(
            io.ktor.plugin.features.DockerPortMapping(
                80,
                8080,
                io.ktor.plugin.features.DockerPortMappingProtocol.TCP
            )
        ))
    }
}

この場合、http://0.0.0.0:80 でサーバーにアクセスできます。

外部レジストリ ​

publishImage タスクを使用してプロジェクトの Docker イメージを外部レジストリに公開する前に、ktor.docker.externalRegistry プロパティを使用して外部レジストリを設定する必要があります。このプロパティは、必要なレジストリタイプの設定を提供する DockerImageRegistry インスタンスを受け取ります。

  • DockerImageRegistry.dockerHub: Docker Hub 用の DockerImageRegistry を作成します。
  • DockerImageRegistry.googleContainerRegistry: Google Container Registry 用の DockerImageRegistry を作成します。

以下の例は、Docker Hub レジストリを設定する方法を示しています。

kotlin
ktor {
    docker {
        externalRegistry.set(
            io.ktor.plugin.features.DockerImageRegistry.dockerHub(
                appName = provider { "ktor-app" },
                username = providers.environmentVariable("DOCKER_HUB_USERNAME"),
                password = providers.environmentVariable("DOCKER_HUB_PASSWORD")
            )
        )
    }
}

Docker Hub のユーザー名とパスワードは環境変数から取得されるため、publishImage タスクを実行する前にこれらの値を設定する必要があることに注意してください。

Bash
export DOCKER_HUB_USERNAME=yourHubUsername
export DOCKER_HUB_PASSWORD=yourHubPassword
Bash
setx DOCKER_HUB_USERNAME yourHubUsername
setx DOCKER_HUB_PASSWORD yourHubPassword

手動でのイメージ設定 ​

必要に応じて、独自の Dockerfile を用意して Ktor アプリケーションを含むイメージを組み立てることもできます。

アプリケーションのパッケージ化 ​

最初のステップとして、アプリケーションを依存関係とともにパッケージ化する必要があります。 たとえば、fat JAR や実行可能 JVM アプリケーションなどがあります。

Docker イメージの準備 ​

アプリケーションを Docker 化するために、マルチステージビルド (multi-stage builds) を使用します。

  1. まず、Gradle/Maven の依存関係のキャッシングを設定します。このステップは任意ですが、ビルド全体の速度が向上するため推奨されます。
  2. 次に、gradle/maven イメージを使用して、アプリケーションを含む fat JAR を生成します。
  3. 最後に、生成された配布物を JDK イメージに基づいて作成された環境で実行します。

プロジェクトのルートフォルダーに、以下の内容で Dockerfile という名前のファイルを作成します。

docker
# Stage 1: Cache Gradle dependencies
FROM gradle:latest AS cache
RUN mkdir -p /home/gradle/cache_home
ENV GRADLE_USER_HOME=/home/gradle/cache_home
COPY build.gradle.* gradle.properties /home/gradle/app/
COPY gradle /home/gradle/app/gradle
WORKDIR /home/gradle/app
RUN gradle dependencies --no-daemon

# Stage 2: Build Application
FROM gradle:latest AS build
COPY --from=cache /home/gradle/cache_home /home/gradle/.gradle
COPY --chown=gradle:gradle . /home/gradle/src
WORKDIR /home/gradle/src
# Build the fat JAR, Gradle also supports shadow
# and boot JAR by default.
RUN gradle buildFatJar --no-daemon

# Stage 3: Create the Runtime Image
FROM amazoncorretto:22 AS runtime
EXPOSE 8080
RUN mkdir /app
COPY --from=build /home/gradle/src/build/libs/*.jar /app/ktor-docker-sample.jar
ENTRYPOINT ["java","-jar","/app/ktor-docker-sample.jar"]
Docker
# Stage 1: Cache Maven dependencies
FROM maven:3.8-amazoncorretto-21 AS cache
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline

# Stage 2: Build Application
FROM maven:3.8-amazoncorretto-21 AS build
WORKDIR /app
COPY --from=cache /root/.m2 /root/.m2
COPY . .
RUN mvn clean package

# Stage 3: Create the Runtime Image
FROM amazoncorretto:21-slim AS runtime
EXPOSE 8080
WORKDIR /app
COPY --from=build /app/target/*-with-dependencies.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

最初のステージにより、ビルド関連ファイルに変更があった場合にのみ依存関係が再ダウンロードされるようになります。最初のステージを使用しない場合、または他のステージで依存関係がキャッシュされない場合、ビルドごとに依存関係がインストールされます。

2 番目のステージでは、fat JAR がビルドされます。なお、Gradle はデフォルトで shadow JAR および boot JAR もサポートしています。

ビルドの 3 番目のステージは次のように動作します。

  • 使用するイメージを指定します。
  • 公開するポートを指定します(これによってポートが自動的に公開されるわけではなく、コンテナの実行時に公開されます)。
  • ビルド出力の内容をフォルダーにコピーします。
  • アプリケーションを実行します (ENTRYPOINT)。

この例では Amazon Corretto の Docker イメージを使用していますが、以下のような他の適切な代替イメージに置き換えることもできます。

Docker イメージのビルドと実行 ​

次のステップは、Docker イメージをビルドしてタグ付けすることです。

bash
docker build -t my-application .

最後に、イメージを起動します。

bash
docker run -p 8080:8080 my-application

これにより Ktor サーバーが起動し、https://0.0.0.0:8080 で応答します。