​Docker

Start Kestra in a single Docker container.

Make sure that Docker is running. Then, you can start Kestra in a single command using Docker (if you run it on Windows, make sure to use WSL):

docker run --pull=always --rm -it -p 8080:8080 --user=root \
 -v /var/run/docker.sock:/var/run/docker.sock \
 -v /tmp:/tmp kestra/kestra:latest-full server local

Open http://localhost:8080 in your browser to launch the UI and start building your first flow.

Configuration

Using a configuration file

You can adjust Kestra's configuration using a file passed to the Docker container as a bind volume.

First, create a configuration file, for example, in a file named application.yaml:

datasources:
  postgres:
    url: jdbc:postgresql://postgres:5432/kestra
    driverClassName: org.postgresql.Driver
    username: kestra
    password: k3str4
kestra:
  server:
    basic-auth:
      enabled: false
      username: "admin@kestra.io" # it must be a valid email address
      password: kestra
  repository:
    type: postgres
  storage:
    type: local
    local:
      base-path: "/app/storage"
  queue:
    type: postgres
  tasks:
    tmp-dir:
      path: "/tmp/kestra-wd/tmp"
        url: "http://localhost:8080/"

Note: this configuration is taken from our official docker-compose.yaml file and uses a PostgreSQL database, you may want to retrieve it there to be sure it is accurate.

Then, change the command to mount the file to the container and start Kestra with the configuration file; we also adjust the Kestra command to start a standalone version as we now have a PostgreSQL database as a backend.

docker run --pull=always --rm -it -p 8080:8080 --user=root \
 -v $PWD/application.yaml:/etc/config/application.yaml
 -v /var/run/docker.sock:/var/run/docker.sock \
 -v /tmp:/tmp kestra/kestra:latest-full server standalone --config /etc/config/application.yaml

Using the KESTRA_CONFIGURATION environment variable

You can adjust the Kestra configuration with a KESTRA_CONFIGURATION passed to the Docker container via the -e options. This environment variable must be a valid YAML string.

Managing a large configuration via a single YAML string can be tedious. To make that easier, you can leverage a configuration file.

First, define an environment variable:

export KESTRA_CONFIGURATION="datasources:
          postgres:
            url: jdbc:postgresql://postgres:5432/kestra
            driverClassName: org.postgresql.Driver
            username: kestra
            password: k3str4
        kestra:
          server:
            basic-auth:
              enabled: false
              username: "admin@kestra.io" # it must be a valid email address
              password: kestra
          repository:
            type: postgres
          storage:
            type: local
            local:
              base-path: "/app/storage"
          queue:
            type: postgres
          tasks:
            tmp-dir:
              path: /tmp/kestra-wd/tmp
          url: http://localhost:8080/"

Note: this configuration is taken from our official docker-compose.yaml file and uses a PostgreSQL database, you may want to retrieve it there to be sure it is accurate.

Then pass this environment variable in the Docker command and adjust the Kesra command to run the standalone server:

docker run --pull=always --rm -it -p 8080:8080 --user=root \
 -e KESTRA_CONFIGURATION=$KESTRA_CONFIGURATION
 -v /var/run/docker.sock:/var/run/docker.sock \
 -v /tmp:/tmp kestra/kestra:latest-full server standalone

Official Docker images

The official Kestra Docker images are available on DockerHub for both linux/amd64 and linux/arm64 platforms.

We provide two image variants:

• kestra/kestra:*
• kestra/kestra:*-full

Both variants are based on the eclipse-temurin:21-jre Docker image.

The kestra/kestra:*-full images contain all Kestra plugins in their latest version. The kestra/kestra:* images do not contain any plugins. We recommend using the full version.

Docker image tags

We provide the following tags for each Docker image:

• latest: the default image with the latest stable release.
  • Full variant: latest-full
• v<release-version>: image for a specific Kestra release.
  • Full variant: v<release-version>-full.
• release: the preview image of the next release.
  • Full variant: release-full
• develop: an image based on the develop branch that changes daily and contains unstable features we are working on.
  • Full variant: develop-full.

Build a custom Docker image

If the base or full image doesn't contain package dependencies you need, you can build a custom image by using the Kestra base image and adding the required binaries and dependencies.

Add custom binaries

The following Dockerfile creates an image from the Kestra base image and adds the golang binary and Python packages:

ARG IMAGE_TAG=latest
FROM kestra/kestra:$IMAGE_TAG

RUN mkdir -p /app/plugins && \
  apt-get update -y && \
  apt-get install -y --no-install-recommends golang && \
  apt-get install -y pip && \
  pip install pandas==2.0.3 requests==2.31.0 && \
  apt-get clean && rm -rf /var/lib/apt/lists/* /var/tmp/*

Add plugins to a Docker image

By default, the base Docker image kestra/kestra:latest does not contain any plugins (unless you use the kestra/kestra:latest-full version). You can add specific plugins to the base image and build a custom image.

The following example Dockerfile creates an image from the base image and adds the plugin-notifications, storage-gcs and plugin-gcp binaries using the command kestra plugins install:

ARG IMAGE_TAG=latest
FROM kestra/kestra:$IMAGE_TAG

RUN /app/kestra plugins install \
  io.kestra.plugin:plugin-notifications:LATEST \
  io.kestra.storage:storage-gcs:LATEST \
  io.kestra.plugin:plugin-gcp:LATEST

Add custom plugins to a Docker image

The above example Dockerfile installs plugins that have already been published to Maven Central. If you are developing a custom plugin, make sure to build it. Once the shadowJar is built, add it to the plugins directory:

ARG IMAGE_TAG=latest
FROM kestra/kestra:$IMAGE_TAG

RUN mkdir -p /app/plugins

COPY /build/libs/*.jar /app/plugins

Add custom plugins from a Git repository

If you would like to build custom plugins from a specific Git repository, you can use the following approach:

FROM openjdk:17-slim as stage-build
WORKDIR /
USER root

RUN apt-get update -y
RUN apt-get install git -y && \
    git clone https://github.com/kestra-io/plugin-aws.git

RUN cd plugin-aws && ./gradlew :shadowJar

FROM kestra/kestra:latest-full

# https://github.com/WASdev/ci.docker/issues/194#issuecomment-433519379
USER root

RUN mkdir -p /app/plugins && \
  apt-get update -y && \
  apt-get install -y --no-install-recommends golang && \
  apt-get install -y pip && \
  pip install pandas==2.0.3 requests==2.31.0 && \
  apt-get clean && rm -rf /var/lib/apt/lists/* /var/tmp/*

RUN rm -rf /app/plugins/plugin-aws-*.jar
COPY --from=stage-build /plugin-aws/build/libs/plugin-aws-*.jar /app/plugins

This multi-stage Docker build allows you to overwrite a plugin that has already been installed. In this example, the AWS plugin is by default already included in the kestra/kestra:latest-full image. However, it's overwritten by a plugin built in the first Docker build stage.