Skip to content
Klutch.sh Docs

Deploying a Kestra App

Introduction

Kestra is an open-source orchestration and data workflow platform. Deploying Kestra with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for flows, logs, and execution data—all from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for dependable automation.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Kestra config (GitHub is the only supported git source)
  • Docker familiarity and basic Kestra/Java knowledge
  • PostgreSQL credentials (recommended backend) and optional object storage credentials

For onboarding, see the Quick Start.

Architecture and ports

  • Kestra serves HTTP on 8080 for UI and API; set the internal container port to 8080 in Klutch.sh.
  • PostgreSQL should run as a separate Klutch.sh TCP app, exposed on port 8000, connected internally on 5432.
  • Persistent storage is recommended for logs, execution data, and plugins.

Repository layout

kestra/
├── config/                 # application.yml and secrets templates
├── flows/                  # Example flow definitions
├── plugins/                # Optional custom plugins (mount as volume)
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Test Kestra locally before pushing to GitHub:

Terminal window
docker run --rm -p 8080:8080 \
  -e KESTRA_DATABASE_JDBC_URL=jdbc:postgresql://localhost:5432/kestra \
  -e KESTRA_DATABASE_USERNAME=kestra \
  -e KESTRA_DATABASE_PASSWORD=kestra \
  kestra/kestra:latest server standalone

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec kestra server standalone

Make it executable with chmod +x start.sh.

Dockerfile for Kestra (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM kestra/kestra:latest


WORKDIR /app


# Optional custom config and flows
COPY config /app/config
COPY flows /app/flows


EXPOSE 8080
CMD ["server", "standalone", "--config", "/app/config/application.yml"]

Notes:

  • Pin the image tag (e.g., kestra/kestra:0.14.0) for reproducible builds.
  • If you add plugins, mount them into /app/plugins.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • PORT=8080
  • KESTRA_DATABASE_JDBC_URL=jdbc:postgresql://<host>:<port>/<db>
  • KESTRA_DATABASE_USERNAME=<db-user>
  • KESTRA_DATABASE_PASSWORD=<db-password>
  • KESTRA_SERVER_BASICAUTH_USERNAME=<admin-user> (optional)
  • KESTRA_SERVER_BASICAUTH_PASSWORD=<admin-pass> (optional)
  • JAVA_OPTS=-Xms512m -Xmx1024m (adjust for workload)
  • KESTRA_STORAGE_BUCKET and related credentials if using object storage

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo Kestra uses prebuilt image"
  • NIXPACKS_START_CMD=kestra server standalone
  • NIXPACKS_JDK_VERSION=17

These keep Kestra compatible with Nixpacks defaults when a Dockerfile is absent.

Attach persistent volumes

Add mount paths and sizes in Klutch.sh (no names required):

  • /app/logs — execution logs.
  • /app/data — optional local storage for executions.
  • /app/plugins — custom plugins if you store them on disk.

Ensure these paths are writable inside the container.

Deploy Kestra on Klutch.sh (Dockerfile workflow)

  1. Push your repository (with the Dockerfile at the root) to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose HTTP traffic for Kestra.
  3. Set the internal port to 8080.
  4. Add the environment variables above (database, auth, storage, JVM options, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /app/logs (and /app/data or /app/plugins if used), selecting sizes that fit your workload.
  6. Deploy. Your Kestra instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

For PostgreSQL on Klutch.sh, create a separate TCP app, expose it on port 8000, and point KESTRA_DATABASE_JDBC_URL to that endpoint (internal port 5432).

Sample flow (getting started)

Create flows/hello.yml to verify the deployment:

id: hello_world
namespace: demo
tasks:
  - id: echo
    type: io.kestra.plugin.core.log.Log
    message: "Hello from Kestra on Klutch.sh"

Health checks and production tips

  • Add a reverse proxy health endpoint that checks the UI or API (/ or /api/v1/executions).
  • Enforce HTTPS at the edge; forward HTTP to port 8080 internally.
  • Keep image tags pinned; upgrade intentionally across the Kestra ecosystem.
  • Monitor disk usage on /app/logs and /app/data; resize volumes proactively.
  • Back up PostgreSQL regularly; do not rely on container filesystems for durability.

Kestra on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and port 8080 configured, you can orchestrate reliable workflows without extra YAML or workflow overhead.