OpenRun: GitOps-платформа для внутренних инструментов

Платформа развёртывания для внутренних инструментов, создаваемых с упором на код (code-first). Превращает сгенерированный код в защищённые внутренние инструменты с поддержкой GitOps, RBAC и аудита. Легко разворачивается на одном узле с Docker/Podman или в кластере Kubernetes.

Обзор

OpenRun — платформа развёртывания веб-приложений с открытым исходным кодом под лицензией Apache 2.0, предназначенная для внутренних инструментов. OpenRun позволяет декларативно развёртывать контейнеризованные веб-приложения. Платформа поддерживает как одноузловое развёртывание, так и работу в кластере Kubernetes. OpenRun обеспечивает декларативное сине-зелёное развёртывание (blue-green deployment) на основе GitOps, управление доступом через OAuth/OIDC/SAML, управление TLS-сертификатами и секретами. Платформа создана для команд, которым нужно удобно развёртывать внутренние инструменты, и поддерживает полноценный ролевой контроль доступа (RBAC). Приложения OpenRun разворачиваются напрямую из git-репозитория — сервер сборки не требуется. OpenRun масштабирует простаивающие приложения до нуля и поддерживает атомарные обновления сразу нескольких приложений.

К уникальным возможностям OpenRun относятся:

Создание приложений и управление ими декларативно, через GitOps
Простое переключение с одноузлового режима на Kubernetes без каких-либо изменений в конфигурации
Маршрутизация по домену или по пути с автоматическим TLS
Аутентификация через OAuth/OpenID/SAML/сертификаты
RBAC для административных операций и для доступа к приложениям
Масштабирование простаивающих приложений до нуля
Поэтапное (staged) развёртывание изменений кода и конфигурации
Атомарные (всё или ничего) обновления нескольких приложений

В этом репозитории размещён исходный код OpenRun. Исходные материалы сайта с документацией openrun.dev находятся в папке docs. Спецификации приложений (AppSpecs) — шаблоны для создания приложений — определены в репозитории appspecs. Примеры приложений находятся в репозитории apps.

FAQ

Чем OpenRun отличается от других решений для развёртывания, таких как Coolify/Dokku/CapRover и т. п.?

Основные отличия:

OpenRun декларативен. После начальной настройки все операции — создание новых приложений и обновление конфигурации существующих — выполняются путём изменения конфигурационного файла в Git, а не через команды CLI или действия в интерфейсе. В большинстве других решений создание и обновление приложений выполняется вручную через CLI или UI, и лишь обновление исходного кода можно провести через Git.
OpenRun умеет разворачивать приложения как на одной машине с Docker/Podman, так и в кластере Kubernetes. Большинство других решений Kubernetes не поддерживают.
OpenRun реализован как веб-сервер и не зависит от внешних веб-серверов вроде Nginx или Traefik. Это упрощает использование и позволяет реализовать такие функции, как масштабирование до нуля и аутентификацию OAuth/SAML/по сертификатам с RBAC.
OpenRun поддерживает поэтапное развёртывание и автоматическую настройку среды разработки — возможности, которых нет в других решениях.

Зачем нужна декларативная конфигурация?

Императивные операции через CLI или UI просты для старта, но затрудняют отслеживание изменений и откат обновлений. При декларативном подходе все изменения хранятся под версионным контролем. Создать новое окружение легко, поскольку всё описано в Git. Если несколько человек из команды вносят изменения в конфигурацию, декларативными системами управлять значительно проще.

Именно декларативность делает Kubernetes и Terraform настолько полезными. OpenRun привносит декларативную конфигурацию в развёртывание веб-приложений. Вместо того чтобы писать страницы YAML, каждое приложение описывается несколькими строками на Starlark (язык, похожий на Python). В качестве примера см. utils.star.

Какие типы приложений можно разворачивать с помощью OpenRun?

OpenRun умеет разворачивать любое веб-приложение, работающее в одном контейнере. Поддерживаются AppSpecs, которые позволяют развёртывать приложения на таких фреймворках, как Streamlit, Gradio, FastHTML, NiceGUI, Shiny и Reflex, без какой-либо дополнительной настройки. Для фреймворков с готовым AppSpec Dockerfile не нужен и никаких изменений в исходном коде приложения не требуется. Для фреймворков без AppSpec в репозитории с исходным кодом должен присутствовать Dockerfile.

OpenRun не поддерживает приложения, для которых требуется несколько контейнеров с Docker Compose. Целевой сценарий использования — внутренние инструменты, обращающиеся к существующим API, и веб-приложения с внешне управляемой базой данных.

Поддерживает ли OpenRun командное развёртывание внутренних инструментов?

Да, развёртывание внутренних инструментов командами — это один из целевых сценариев использования. Для него реализованы следующие возможности:

Декларативная конфигурация: управление приложениями декларативно в Git позволяет команде следовать стандартному жизненному циклу разработки программного обеспечения (SDLC) для конфигурации.
OAuth/OIDC/SAML с RBAC: управление доступом к приложениям через RBAC.
Журналы аудита: все операции и вызовы API автоматически фиксируются в журнале аудита.

Как развёртывается сам OpenRun?

OpenRun легко разворачивается на одном узле (Linux, Windows или macOS) с использованием SQLite для хранения метаданных. Единственная зависимость — Docker или Podman. Для развёртывания на нескольких машинах используется внешняя база данных Postgres.

OpenRun также можно развернуть в Kubernetes с помощью Helm-чарта. В Kubernetes OpenRun избавляет от необходимости настраивать систему сборки вроде Jenkins, CD через ArgoCD и IDP вроде BackStage. Приложения, развёрнутые через OpenRun, работают как сервисы Kubernetes, а сам OpenRun выступает в роли API-сервера и маршрутизатора запросов.

Обзор архитектуры

Одноузловая архитектура

architecture-beta
    service client(internet)[Client]

    group host(server)[Node]
    service openrun(server)[OpenRun Server] in host
    service sqlite(database)[SQLite Metadata] in host

    group cm(server)[Docker or Podman] in host
    junction split in cm
    service app1(server)[App1] in cm
    service app2(server)[App2] in cm

    client:R --> L:openrun
    openrun:B --> T:sqlite
    openrun:R -- L:split
    split:T --> B:app1
    split:B --> T:app2

Архитектура Kubernetes

architecture-beta
    service client(internet)[Client]
    service postgres(database)[Postgres Metadata]
    service registry(server)[Container Registry]

    group k8s(server)[Kubernetes]
    service openrun(server)[OpenRun] in k8s

    group apps(server)[Deployed Apps] in k8s
    junction split in apps
    service app1(server)[App1] in apps
    service app2(server)[App2] in apps

    client:R --> L:openrun
    postgres:R <-- T:openrun
    registry:R <-- B:openrun

    openrun:R -- L:split
    split:T --> B:app1
    split:B --> T:app2

Возможности

OpenRun позволяет:

Развёртывать контейнеризованные приложения — OpenRun самостоятельно выполняет сборку и управляет жизненным циклом контейнеров
Автоматически генерировать форм-ориентированный пользовательский интерфейс для серверных действий
Добавлять аутентификацию через OAuth/OIDC/SAML и RBAC для управления доступом к приложениям

Для всех приложений OpenRun поддерживает:

Декларативное развёртывание приложений
Атомарные обновления (всё или ничего) для нескольких приложений
Режим промежуточного стенда для обновлений приложений — позволяет убедиться, что изменения кода и конфигурации работают в проде до их публикации
Поддержку создания предварительных приложений для проверки изменений кода
Интеграцию с GitHub — прямое развёртывание приложений из репозитория GitHub
Автоматическое создание SSL-сертификатов на основе certmagic
Аутентификацию через OAuth/OIDC/SAML
Маршрутизацию по домену и по пути на уровне приложения
Интеграцию с менеджерами секретов для безопасного доступа к секретам

Для контейнеризованных приложений OpenRun поддерживает:

Управление сборкой образов в режимах разработки и продакшна
Передачу параметров контейнеру
Сборку приложений по спецификации без изменений в исходном коде репозитория для поддерживаемых фреймворков (Flask, Streamlit и репозиториев с Dockerfile)
Поддержку приостановки простаивающих контейнеров приложений

Для создания приложений на основе Hypermedia OpenRun поддерживает:

Автоматическую обработку ошибок
Автоматическое создание ECMAScript-модулей с помощью esbuild для зависимостей
Интеграцию с TailwindCSS и DaisyUI в режиме наблюдения
Выполнение серверного кода приложения в песочнице безопасности с разрешительным списком (allowlist) прав доступа
Отсутствие этапа сборки — артефакты разработки сразу готовы к использованию в продакшне
Хранение данных приложения с помощью SQLite
Виртуальную файловую систему с именами файлов на основе хэша содержимого, хранящимися в базе данных SQLite, что позволяет агрессивно кешировать статический контент
Сжатие статических артефактов с помощью Brotli и поддержку HTTP Early Hints для повышения производительности

Дорожная карта

Планируемые возможности OpenRun:

Добавление новых спецификаций приложений для поддержки дополнительных фреймворков из коробки
Масштабирование приложений в Kubernetes на основе числа одновременных запросов к API (масштабирование по метрикам CPU/памяти уже поддерживается)
Поддержка разрешительного списка плагинов на уровне сервера (сейчас каждый вызов плагина требует явного подтверждения на уровне приложения)
Поддержка использования одного образа контейнера для промежуточного стенда и продакшна, когда это возможно
Поддержка режима верифицированного продвижения (verified promote), при котором перед продвижением выполняются проверки работоспособности приложения на промежуточном стенде

Установка

Сертификаты и пароль по умолчанию

OpenRun управляет TLS-сертификатами через Let’s Encrypt для продакшн-окружений. Для разработки OpenRun использует mkcert для локальных сертификатов. При установке OpenRun через brew mkcert устанавливается автоматически.

Для контейнерных приложений на машине должен быть установлен и запущен Docker, Podman или Orbstack. OpenRun автоматически определяет, какой менеджер контейнеров использовать.

Установка OpenRun на macOS/Linux

Для установки на macOS/Linux выполните:

curl -sSL https://openrun.dev/install.sh | sh

Откройте новый терминал (чтобы применить обновлённые переменные окружения) и запустите openrun server start для запуска сервиса OpenRun.

Установка через Brew

Для установки через brew выполните:

brew tap openrundev/homebrew-openrun
brew install openrun
brew services start openrun

Установка на Windows

Для установки на Windows выполните:

powershell -Command "irm https://openrun.dev/install.ps1 | iex"

Откройте новое командное окно (чтобы применить обновлённые переменные окружения) и запустите openrun server start для запуска сервиса OpenRun.

Установка на Kubernetes

Подробности установки с помощью Helm-чарта и Terraform-инфраструктуры см. в документации по Kubernetes.

Установка приложений

После запуска сервера OpenRun откройте новое окно и выполните следующую команду для декларативной установки приложений:

openrun apply --approve github.com/openrundev/openrun/examples/utils.star

Чтобы настроить фоновую синхронизацию, которая автоматически применяет актуальную конфигурацию приложений, выполните:

openrun sync schedule --approve --promote github.com/openrundev/openrun/examples/utils.star

Для установки приложений через CLI (императивный режим) выполните:

openrun app create --approve github.com/openrundev/apps/system/list_files /files
openrun app create --approve github.com/openrundev/apps/system/disk_usage /disk_usage
openrun app create --approve github.com/openrundev/apps/utils/bookmarks /book

Откройте https://localhost:25223 для просмотра списка приложений. Приложение для мониторинга диска доступно по адресу https://localhost:25223/disk_usage (порт 25222 для HTTP). Менеджер закладок — по адресу https://localhost:25223/book, приложение для просмотра файлов — по адресу https://localhost:25223/files.

Информацию об установке см. в разделе installation, параметры конфигурации — в разделе config options. Для включения сертификатов Let’s Encrypt см. Automatic SSL.

Бинарные файлы релизов доступны на странице releases. Инструкции по сборке из исходного кода см. в разделе install from source.

Для установки контейнеризованного приложения убедитесь, что запущен Docker или Podman, и выполните:

openrun app create --spec python-streamlit --branch master --approve github.com/streamlit/streamlit-example /streamlit

Если исходный репозиторий содержит Dockerfile или Containerfile, выполните:

openrun app create --spec container --approve <source_path> /myapp

Сборка из исходного кода

Для установки релизной сборки следуйте инструкциям в документации по установке.

Для сборки из исходного кода:

Убедитесь, что установлена актуальная версия Go — не ниже 1.21.0
Склонируйте репозиторий OpenRun и перейдите в папку с ним
Соберите бинарный файл openrun и поместите его в нужное место, например в $HOME

# Убедитесь, что go есть в $PATH
mkdir $HOME/openrun_source && cd $HOME/openrun_source
git clone -b main https://github.com/openrundev/openrun && cd openrun
export OPENRUN_HOME=$HOME/clhome && mkdir -p $OPENRUN_HOME/config
go build -o $OPENRUN_HOME/openrun ./cmd/openrun/

Начальная конфигурация при установке из исходного кода

Для использования сервиса OpenRun необходим начальный конфигурационный файл с паролем сервиса и рабочей директорией. В инструкциях ниже предполагается, что конфигурационный файл находится по пути $HOME/clhome/openrun.toml, а рабочая директория — $HOME/clhome.

Создайте директорию clhome
Создайте файл openrun.toml и сгенерируйте случайный пароль для учётной записи admin

cd $OPENRUN_HOME
git clone -C config https://github.com/openrundev/appspecs
$OPENRUN_HOME/openrun password > $OPENRUN_HOME/openrun.toml
$OPENRUN_HOME/openrun server start

По умолчанию сервис запускается по адресу https://localhost:25223 (HTTP-порт 25222).

Документация

Документация OpenRun находится по адресу https://openrun.dev/docs/. Об ошибках в документации сообщайте через GitHub Issues в репозитории docs.

Получение помощи

Для обсуждения тем, связанных с OpenRun, используйте GitHub Discussions. Для сообщений об ошибках и запросов новых функций используйте баг-трекер. Ещё один вариант — сообщество OpenRun Discord.

Участие в разработке

Pull-запросы для исправления ошибок и улучшений приветствуются. Для исправлений, связанных с поведением приложений, обращайтесь к юнит-тестам приложений. Они выполняются в рамках стандартных юнит-тестов командой go test ./…. Для изменений, затрагивающих API, OpenRun использует библиотеку commander-cli для автоматизированного тестирования CLI. Для запуска CLI-тестов выполните gmake test из корневой директории OpenRun.