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):

bash

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 server local

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

The above command starts Kestra with an embedded H2 database. If you want to use a persistent database backend with Postgres and more configurability, follow the Docker Compose installation.

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:

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.

bash

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:

bash

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:

bash

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, including all plugins.
latest-no-plugins: the default image with the latest stable release, excluding all plugins.
v<release-version>: image for a specific Kestra release, including all plugins.
v<release-version>-no-plugins: image for a specific Kestra release, excluding all plugins.
develop: an image based on the develop branch that changes daily and contains unstable features we are working on, including all plugins.
develop-no-plugins: an image based on the develop branch that changes daily and contains unstable features we are working on, excluding all plugins.

The default Kestra image kestra/kestra:latest already includes all plugins. To use a lightweight version of Kestra without plugins, add a suffix *-no-plugins.

Recommended images for production

We recommend using the latest image for production deployments. This image includes the latest stable release and optionally also all plugins:

kestra/kestra:latest — contains the latest stable version of Kestra and all plugins
kestra/kestra:latest-no-plugins — contains the latest stable version of Kestra without any plugins.

If your deployment startegy is to pin the version, make sure to change the image as follows (here, based on the v0.18.0 release):

kestra/kestra:v0.18.0 if you want to have all plugins included in the image
kestra/kestra:v0.18.0-no-plugins if you prefer to use only your custom plugins.

Recommended images for development

The most recently developed (but not yet released) features and bug fixes are included in the develop image. This image is updated daily and contains the latest changes from the develop branch:

kestra/kestra:develop if you want to have all plugins included in the image
kestra/kestra:develop-no-plugins if you prefer to use only your custom plugins.

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:

dockerfile

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:

dockerfile

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:

dockerfile

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:

dockerfile

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.

Was this page helpful?

DocsInstallation Guide

InstallationDocker Compose

​Docker

Docker