Docker
In this section, we'll see how to use the Ktor Gradle plugin for packaging, running, and deploying applications using Docker.
Install the Ktor plugin
To install the Ktor plugin, add it to the plugins
block of your build.gradle.(kts)
file:
Plugin tasks
After installing the plugin, the following tasks are available for packaging, running, and deploying applications:
buildImage
: builds a project's Docker image to a tarball. This task generates ajib-image.tar
file in thebuild
directory. You can load this image to a Docker daemon using the docker load command:docker load < build/jib-image.tarpublishImageToLocalRegistry
: builds and publishes a project's Docker image to a local registry.runDocker
: builds a project's image to a Docker daemon and runs it. Executing this task will launch the Ktor server, responding onhttp://0.0.0.0:8080
by default. If your server is configured to use another port, you can adjust port mapping.publishImage
: builds and publishes a project's Docker image to an external registry such as Docker Hub or Google Container Registry. Note that you need to configure the external registry using the ktor.docker.externalRegistry property for this task.
Note that by default, these tasks build the image with the ktor-docker-image
name and latest
tag. You can customize these values in the plugin configuration.
Configure the Ktor plugin
To configure the Ktor plugin settings related to Docker tasks, use the ktor.docker
extension in your build.gradle.(kts)
file:
JRE version
The jreVersion
property specifies the JRE version to use in the image:
Image name and tag
If you need to customize the image name and tag, use the localImageName
and imageTag
properties, respectively:
Port mapping
By default, the runDocker task publishes the 8080
container port to the 8080
Docker host port. If required, you can change these ports using the portMappings
property. This might be useful if your server is configured to use another port.
The example below shows how to map the 8080
container port to the 80
Docker host port.
In this case, you can access the server on http://0.0.0.0:80
.
External registry
Before publishing a project's Docker image to an external registry using the publishImage task, you need to configure the external registry using the ktor.docker.externalRegistry
property. This property accepts the DockerImageRegistry
instance, which provides configuration for the required registry type:
DockerImageRegistry.dockerHub
: creates aDockerImageRegistry
for Docker Hub.DockerImageRegistry.googleContainerRegistry
: creates aDockerImageRegistry
for Google Container Registry.
The example below shows how to configure the Docker Hub registry:
Note that the Docker Hub name and password are fetched from the environment variables, so you need to set these values before running the publishImage
task:
Manual image configuration
If required, you can provide your own Dockerfile
to assemble an image with a Ktor application.
Package the application
As a first step, you need to package your application along with its dependencies. For example, this might be a fat JAR or an executable JVM application.
Prepare Docker image
To dockerize the application, we'll use multi-stage builds:
First, we'll set up caching for Gradle/Maven dependencies. This step is optional, but recommended as it improves the overall build speed.
Then, we'll use the
gradle
/maven
image to generate a fat JAR with the application.Finally, the generated distribution will be run in the environment created based on the JDK image.
In the root folder of the project, create a file named Dockerfile
with the following contents:
The first stage ensures dependencies will be re-downloaded only when there is a change to the build related files. If the first stage is not used, or dependencies are not cached in other stages, dependencies will be installed in every build.
In the second stage the fat JAR is built. Note that Gradle also supports shadow and boot JAR by default.
The third stage of the build works in the following way:
Indicates what image is going to be used.
Specifies the exposed port (this does not automatically expose the port, which is done when running the container).
Copies the contents from the build output to the folder.
Runs the application (
ENTRYPOINT
).
Build and run the Docker image
The next step is to build and tag the Docker image:
Finally, start the image:
This will launch the Ktor server, responding on https://0.0.0.0:8080
.