Docker
代码示例: deployment-ktor-plugin
在本节中,你将学习如何使用 Ktor Gradle 插件 通过 Docker 打包、运行和部署应用程序。
安装 Ktor 插件
plugins {
alias(ktorLibs.plugins.ktor)
}plugins {
alias(ktorLibs.plugins.ktor)
}如果同时应用 Ktor Gradle 插件与 Kotlin Multiplatform Gradle 插件,Docker 集成将自动禁用。 要想将它们一起使用:
- 创建一个仅限 JVM 的项目,并如上所示应用 Ktor Gradle 插件。
- 将 Kotlin Multiplatform 项目作为依赖项添加到该仅限 JVM 的项目中。
如果此变通方法未能解决你的问题,请在 KTOR-8464 中留言告知我们。
插件任务
安装插件后,以下任务可用于打包、运行和部署应用程序:
buildImage:将项目的 Docker 镜像构建为归档包(tarball)。该任务会在build目录下生成一个jib-image.tar文件。你可以使用 docker load 命令将此镜像加载到 Docker 守护进程中:Bashdocker load < build/jib-image.tarpublishImageToLocalRegistry:构建项目的 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 扩展程序:
ktor {
docker {
// ...
}
}JRE 版本
jreVersion 属性指定镜像中使用的 JRE 版本:
ktor {
docker {
jreVersion.set(JavaVersion.VERSION_17)
}
}镜像名称与标签
如果需要自定义镜像名称和标签,请分别使用 localImageName 和 imageTag 属性:
ktor {
docker {
localImageName.set("sample-docker-image")
imageTag.set("0.0.1-preview")
}
}端口映射
默认情况下,runDocker 任务会将 8080 容器端口发布到 8080 Docker 主机端口。 如有需要,可以使用 portMappings 属性更改这些端口。 如果你的服务器已配置为使用其他端口,这会非常有用。
下面的示例展示了如何将 8080 容器端口映射到 80 Docker 主机端口。
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 注册表:
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 任务之前需要设置这些值:
export DOCKER_HUB_USERNAME=yourHubUsername
export DOCKER_HUB_PASSWORD=yourHubPasswordsetx DOCKER_HUB_USERNAME yourHubUsername
setx DOCKER_HUB_PASSWORD yourHubPassword手动配置镜像
如有需要,你可以提供自己的 Dockerfile 来组装包含 Ktor 应用程序的镜像。
打包应用程序
第一步,你需要将应用程序及其依赖项打包。 例如,这可以是一个 fat JAR 或一个可执行的 JVM 应用程序。
准备 Docker 镜像
为了将应用程序容器化,我们将使用多阶段构建:
- 首先,我们将为 Gradle/Maven 依赖项设置缓存。此步骤是可选的,但建议执行,因为它可以提升整体构建速度。
- 随后,我们将使用
gradle/maven镜像来生成包含该应用程序的 fat JAR。 - 最后,生成的发行包将在基于 JDK 镜像创建的环境中运行。
在项目的根文件夹中,创建一个名为 Dockerfile 的文件,其内容如下:
# 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"]# 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"]第一阶段确保仅在构建相关文件发生更改时才重新下载依赖项。如果未使用第一阶段,或者未在其他阶段缓存依赖项,则每次构建都会安装依赖项。
在第二阶段中构建 fat JAR。请注意,Gradle 默认还支持 shadow 和 boot JAR。
构建的第三阶段按以下方式工作:
- 指明将要使用的镜像。
- 指定公开的端口(这不会自动暴露端口,暴露端口是在运行容器时完成的)。
- 将构建输出的内容复制到文件夹中。
- 运行应用程序(
ENTRYPOINT)。
本示例使用的是 Amazon Corretto Docker 镜像,但你也可以将其替换为任何其他合适的替代方案,例如:
构建并运行 Docker 镜像
下一步是构建并标记 Docker 镜像:
docker build -t my-application .最后,启动镜像:
docker run -p 8080:8080 my-application这将启动 Ktor 服务器,并在 https://0.0.0.0:8080 上响应请求。
