Встановлення Kestra на VPS: оркестрація завдань, Docker, PostgreSQL, SSL і розклади

Конфігурація Kestra, PostgreSQL і SSL

Підготовка секретів

Згенеруйте окремі довгі паролі для PostgreSQL і базової HTTP-автентифікації Caddy. Файл .env не додавайте до Git і не надсилайте в месенджери. Права 600 забороняють читання файлу іншими користувачами сервера.

cd /opt/kestra
POSTGRES_PASSWORD=$(openssl rand -base64 32 | tr -d '\n')
CADDY_PASSWORD=$(openssl rand -base64 24 | tr -d '\n')

cat > .env <<EOF
POSTGRES_DB=kestra
POSTGRES_USER=kestra
POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
KESTRA_DOMAIN=kestra.example.com
CADDY_USER=admin
CADDY_PASSWORD=${CADDY_PASSWORD}
EOF

chmod 600 .env

Замініть kestra.example.com на власний домен. До запуску Caddy перевірте DNS: команда має повернути публічний IP вашого VPS.

source /opt/kestra/.env
getent ahostsv4 "$KESTRA_DOMAIN"
curl -4 ifconfig.me ; echo

Конфігурація Kestra

Створіть файл config/application.yml. У ньому Kestra використовує PostgreSQL як repository і queue backend. Локальне storage підходить для одного вузла Kestra. У разі переходу до кількох серверів storage потрібно перенести в S3-сумісне об’єктне сховище.

cat > /opt/kestra/config/application.yml <<'EOF'
datasources:
  postgres:
    url: jdbc:postgresql://postgres:5432/${POSTGRES_DB}
    driverClassName: org.postgresql.Driver
    username: ${POSTGRES_USER}
    password: ${POSTGRES_PASSWORD}

kestra:
  repository:
    type: postgres
  queue:
    type: postgres
  storage:
    type: local
    local:
      base-path: /app/storage
  tasks:
    tmp-dir:
      path: /tmp/kestra-wd/tmp
  url: https://${KESTRA_DOMAIN}/
  server:
    basic-auth:
      enabled: false

logger:
  levels:
    io.kestra: INFO
EOF

Basic authentication Kestra вимкнена, оскільки зовнішній доступ захищатиме Caddy. Це спрощує роботу з браузером і API, але означає, що Caddy має залишатися єдиною точкою входу. Порт Kestra не публікується назовні.

Docker Compose для Kestra і PostgreSQL

Створіть compose.yml. PostgreSQL не має секції ports, отже, доступний лише контейнерам у внутрішній Docker-мережі. Kestra публікується на 127.0.0.1:8080, тому Caddy на тому самому сервері може до неї звертатися, а інтернет — ні.

cat > /opt/kestra/compose.yml <<'EOF'
services:
  postgres:
    image: postgres:16.6-alpine
    container_name: kestra-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 10
    networks:
      - kestra_internal

  kestra:
    image: kestra/kestra:v0.24.0
    container_name: kestra
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      KESTRA_DOMAIN: ${KESTRA_DOMAIN}
      JAVA_OPTS: "-Xms512m -Xmx1536m"
    command: server standalone --config /etc/kestra/application.yml
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./config/application.yml:/etc/kestra/application.yml:ro
      - kestra_storage:/app/storage
      - kestra_workdir:/tmp/kestra-wd
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:8080/health | grep -q UP"]
      interval: 30s
      timeout: 10s
      retries: 10
      start_period: 60s
    networks:
      - kestra_internal

networks:
  kestra_internal:
    name: kestra_internal

volumes:
  postgres_data:
  kestra_storage:
  kestra_workdir:
EOF

Параметр JAVA_OPTS обмежує heap Java до 1,5 ГБ. На VPS із 4 ГБ RAM це розумна відправна точка: решта пам’яті залишається PostgreSQL, ОС і файловому кешу. На сервері з 8 ГБ RAM можна збільшити -Xmx до 3–4 ГБ після спостереження за реальним споживанням пам’яті.

Запустіть сервіси у фоновому режимі та перевірте їхній статус. Перший запуск може тривати кілька хвилин: Kestra створює таблиці та застосовує міграції в PostgreSQL.

cd /opt/kestra
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 kestra

Перевірте локальний endpoint до налаштування проксі. Відповіддю може бути JSON або HTTP-перенаправлення залежно від версії Kestra, але кодом не має бути 502 або Connection refused.

curl -I http://127.0.0.1:8080/
docker inspect --format='{{.State.Health.Status}}' kestra
docker inspect --format='{{.State.Health.Status}}' kestra-postgres

Налаштування Caddy і HTTPS

Спочатку створіть bcrypt-хеш пароля для Caddy. Команда запросить пароль, який ви зберегли в .env. Не вставляйте пароль у командний рядок: він залишиться в shell history.

source /opt/kestra/.env
read -rsp "Password for Caddy user ${CADDY_USER}: " INPUT_PASSWORD; echo
CADDY_HASH=$(printf '%s' "$INPUT_PASSWORD" | caddy hash-password --stdin)
unset INPUT_PASSWORD
printf '%s\n' "$CADDY_HASH"

Створіть Caddyfile. Замість змінної в конфігурації вкажіть виведений хеш вручну на місці PASTE_BCRYPT_HASH_HERE. Це безпечніше, ніж залишати пароль у відкритому вигляді.

sudo tee /etc/caddy/Caddyfile > /dev/null <<'EOF'
kestra.example.com {
    encode zstd gzip

    basic_auth {
        admin PASTE_BCRYPT_HASH_HERE
    }

    reverse_proxy 127.0.0.1:8080 {
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }

    log {
        output file /var/log/caddy/kestra-access.log
        format json
    }
}
EOF

Замініть домен і хеш у файлі, створіть каталог журналів, потім перевірте синтаксис. Caddy отримує сертифікат автоматично після успішного завантаження конфігурації, якщо DNS уже вказує на сервер і порт 80 доступний ззовні.

sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager

Відкрийте https://kestra.example.com у браузері. Браузер попросить логін і пароль Caddy, після чого відкриється інтерфейс Kestra. Також перевірте TLS із консолі.

curl -I https://kestra.example.com
sudo journalctl -u caddy -n 100 --no-pager

Перший workflow і cron-розклад

Відкрийте Kestra у браузері, створіть namespace, наприклад company.ops, потім перейдіть до розділу Flows і створіть flow. Для першої перевірки вставте наведений нижче YAML. Він записує повідомлення в логи та спрацьовує кожні 15 хвилин.

id: health_report
namespace: company.ops
description: Проверочный workflow с cron-расписанием

triggers:
  - id: every_15_minutes
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "/15    "
    timezone: "Europe/Moscow"

tasks:
  - id: write_log
    type: io.kestra.plugin.core.log.Log
    message: "Kestra работает. Время запуска: {{ execution.startDate }}"

  - id: shell_check
    type: io.kestra.plugin.scripts.shell.Commands
    commands:
      - "date -u"
      - "echo Workflow finished successfully"

Збережіть workflow, натисніть Execute і відкрийте вкладку Executions. Має з’явитися статус SUCCESS. Потім дочекайтеся часу, кратного 15 хвилинам, або тимчасово замініть cron на для тесту щохвилини. Після перевірки поверніть звичайний розклад.

Не зберігайте токени API, ключі S3, паролі баз даних і webhook secrets безпосередньо в YAML. Використовуйте секрети Kestra, змінні середовища або зовнішній secret manager. Для початку можна створювати secrets через інтерфейс у namespace, а згодом підключити Vault, SOPS або хмарний secrets manager.

Резервні копії та обслуговування

Для відновлення Kestra потрібні не лише дані PostgreSQL. Необхідно зберегти конфігураційні файли, файл Compose, Caddyfile, файл секретів .env і persistent storage. PostgreSQL містить метадані, execution history, налаштування та дані черг; storage містить файли, створені завданнями й плагінами.

Локальний backup-скрипт

Наступний скрипт створює стиснений дамп PostgreSQL і архівує каталог конфігурації. Він зберігає останні 14 днів локально. Локальний backup не захищає від видалення VPS, тому потім його потрібно надсилати до S3-сумісного сховища або на окремий сервер.

cat > /opt/kestra/backup-kestra.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

BASE="/opt/kestra"
DATE=$(date +%F_%H-%M-%S)
DEST="${BASE}/backups/${DATE}"

mkdir -p "${DEST}"

cd "${BASE}"
docker compose exec -T postgres pg_dump \
  -U "${POSTGRES_USER}" \
  -d "${POSTGRES_DB}" \
  --format=custom \
  --file="/tmp/kestra_${DATE}.dump"

docker cp kestra-postgres:"/tmp/kestra_${DATE}.dump" \
  "${DEST}/postgres.dump"

docker compose exec -T postgres rm -f "/tmp/kestra_${DATE}.dump"

tar --exclude='backups' \
  --exclude='.git' \
  -czf "${DEST}/kestra-config.tar.gz" \
  -C /opt kestra

docker run --rm \
  -v kestra_kestra_storage:/source:ro \
  -v "${DEST}":/backup \
  alpine:3.20 \
  tar -czf /backup/kestra-storage.tar.gz -C /source .

find "${BASE}/backups" -mindepth 1 -maxdepth 1 -type d -mtime +14 -exec rm -rf {} \;
EOF

chmod 700 /opt/kestra/backup-kestra.sh
cd /opt/kestra && ./backup-kestra.sh
ls -lah /opt/kestra/backups

Ім’я Docker volume зазвичай формується з імені каталогу та імені volume. У цьому випадку проєкт запускається з /opt/kestra, тому volume називається kestra_kestra_storage. Якщо команда повернула помилку про неіснуючий volume, подивіться точну назву через docker volume ls і виправте скрипт.

Надсилання backup до зовнішнього сховища

Для реального захисту зберігайте копії за межами основного VPS. Практичні варіанти: S3-сумісне об’єктне сховище, окремий backup VPS через SSH, Borg repository або Restic repository. Нижче наведено приклад із Restic і S3-сумісним backend. Змінні доступу помістіть в окремий файл із правами 600.

sudo apt install -y restic
sudo tee /etc/kestra-restic.env > /dev/null <<'EOF'
export RESTIC_REPOSITORY="s3:s3.example.net/kestra-backups"
export RESTIC_PASSWORD="CHANGE_TO_A_LONG_UNIQUE_RESTIC_PASSWORD"
export AWS_ACCESS_KEY_ID="CHANGE_ME"
export AWS_SECRET_ACCESS_KEY="CHANGE_ME"
EOF
sudo chmod 600 /etc/kestra-restic.env

Ініціалізуйте репозиторій один раз, потім додайте завантаження даних у кінець backup-скрипта. Перед використанням перевірте параметри endpoint і bucket у вибраного S3-провайдера.

source /etc/kestra-restic.env
restic init
restic backup /opt/kestra/backups
restic snapshots

Додайте щоденний запуск. Cron запускається від користувача ops, тому йому мають бути доступні Docker і файли проєкту.

crontab -e

15 2    /opt/kestra/backup-kestra.sh >> /opt/kestra/backups/backup.log 2>&1
30 2    . /etc/kestra-restic.env && restic backup /opt/kestra/backups && restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune >> /opt/kestra/backups/restic.log 2>&1

Оновлення Kestra без втрати даних

Для одного VPS оновлення — це коротке maintenance window, а не справжнє rolling deployment. Спочатку створіть backup, прочитайте release notes вибраної версії, оновіть тег образу в compose.yml, завантажте образ і перезапустіть лише контейнер Kestra.

cd /opt/kestra
./backup-kestra.sh
docker compose pull kestra
docker compose up -d --no-deps kestra
docker compose logs -f --tail=100 kestra

Після оновлення перевірте інтерфейс, виконання тестового workflow, розклад і міграції бази. Не видаляйте старий образ негайно: він може знадобитися для відкату, якщо нова версія несумісна з використовуваним плагіном. Перед оновленням major-версії PostgreSQL створіть окремий перевірений backup і дотримуйтеся процедури upgrade PostgreSQL, а не просто змінюйте тег контейнера.

Troubleshooting + FAQ

Чому Caddy не отримує TLS-сертифікат і в логах є помилка ACME?

Спочатку перевірте A-запис домену командою getent ahostsv4 kestra.example.com: вона має повертати IP VPS. Потім переконайтеся, що UFW дозволяє TCP-порти 80 і 443, а у провайдера немає додаткового cloud firewall. Перевірте, що інший вебсервер не зайняв порт 80: sudo ss -ltnp | grep ':80\|:443'. Після виправлення DNS і портів виконайте sudo systemctl reload caddy та перегляньте journalctl -u caddy.

Чому в браузері відображається 502 Bad Gateway?

Код 502 означає, що Caddy доступний, але не може підключитися до Kestra. Виконайте docker compose ps у каталозі /opt/kestra: контейнер Kestra має бути у стані running або healthy. Потім перевірте локально curl -I http://127.0.0.1:8080/. Якщо відповіді немає, перегляньте docker compose logs kestra і docker compose logs postgres. Частою причиною є те, що PostgreSQL ще не пройшов healthcheck або вказано неправильні змінні бази.

Kestra постійно перезапускається. Що перевірити?

Почніть із docker compose logs --tail=200 kestra. Помилки підключення до PostgreSQL зазвичай вказують на неправильний пароль, ім’я бази або пошкоджену конфігурацію JDBC. Помилки OutOfMemoryError означають, що VPS не вистачає RAM або параметр -Xmx має надто велике значення. Перевірте пам’ять через free -h і docker stats. На VPS із 2 ГБ RAM краще не запускати PostgreSQL і Kestra з важкими workflows одночасно.

Чому workflow за cron не запускається?

Перевірте, що flow збережено, увімкнено і він не містить помилок у YAML. У cron із п’яти полів вираз /15 * означає кожні 15 хвилин. Переконайтеся, що timezone вказано явно: без нього час може інтерпретуватися в UTC. Відкрийте розділ Executions і знайдіть помилки trigger. Також перегляньте логи: docker compose logs kestra | grep -i schedule. Для тестування тимчасово встановіть розклад щохвилини.

Яка конфігурація VPS підійде мінімально?

Для знайомства з Kestra можна використовувати 1 vCPU, 2 ГБ RAM і 25 ГБ NVMe, але це некомфортний production-варіант. Практичний мінімум для Kestra, PostgreSQL, Caddy і кількох невеликих workflow — 2 vCPU, 4 ГБ RAM і 40–60 ГБ NVMe. Якщо workflow запускають Python, Chromium, Docker-контейнери або обробляють файли, обирайте щонайменше 4 vCPU і 8 ГБ RAM.

Що обрати — VPS чи dedicated для цього завдання?

VPS достатньо для API-автоматизації, SQL-завдань, регулярних звітів, webhook і більшості невеликих ETL-процесів. Dedicated потрібен за постійного значного CPU-навантаження, десятків паралельних container jobs, великих обсягів локальних даних або суворої вимоги до виділених ресурсів. Зазвичай розумніше почати з VPS і стежити за docker stats, навантаженням CPU, IOPS і часом виконання workflow.

Чи можна відкрити PostgreSQL назовні для підключення з DBeaver?

Технічно можна, але для Kestra це зазвичай не потрібно й небезпечно. PostgreSQL має залишатися всередині Docker-мережі. Для адміністративного доступу використовуйте SSH-тунель: ssh -L 5432:127.0.0.1:5432 ops@SERVER_IP, але для цього тимчасово потрібно буде пробросити PostgreSQL лише на localhost. Безпечніший варіант — виконувати SQL-команди через docker compose exec postgres psql безпосередньо на сервері.

Чому backup не бачить Docker volume Kestra?

Спочатку виконайте docker volume ls і знайдіть volume, пов’язаний зі storage. Docker Compose формує ім’я з project name та імені volume, тому воно може відрізнятися від прикладу, якщо проєкт було запущено з іншого каталогу або з параметром -p. Виправте ім’я volume у backup-скрипті. Також перевірте права на каталог /opt/kestra/backups і переконайтеся, що cron запускається від користувача, який входить до групи docker.

Висновки та наступні кроки

Тепер на VPS працює Kestra з PostgreSQL, Docker Compose, HTTPS через Caddy, базовим захистом сервера, cron-розкладами та резервним копіюванням. Інстанс готовий до запуску production-workflow, якщо ви регулярно перевіряєте логи, вільне місце на диску та успішність backup.

1. Створіть окремі namespace для розробки та production, а секрети перенесіть у Kestra Secrets або зовнішній secret manager.
2. Налаштуйте сповіщення в Telegram, Slack або email для execution зі статусом FAILED.
3. За зростання навантаження винесіть storage у S3-сумісне сховище, PostgreSQL — на окремий сервер або managed-базу, а навантаження worker ізолюйте в окремих контейнерах.

Перед будь-яким оновленням Kestra створюйте перевірений backup і тестуйте критичні workflows вручну. Це важливіше за автоматичне оновлення образів і дає змогу швидко виконати відкат у разі несумісності плагінів або змін у конфігурації.