Holkas
Написать в поддержку Поддержка

Установка

Параметры запуска

Настройте вход по паролю, Local без входа или SSO через Keycloak, порт, место хранения данных и срок жизни файлов операций. Сначала — практический пример, ниже — справочник переменных для Docker и Windows.

На этой странице

Задайте срок хранения 90 дней

Допустим, вам нужно разбирать планы и журналы спустя два месяца после переноса. В существующий compose.yaml добавьте параметр в services.holkas.environment. Фрагмент ниже дополняет вашу конфигурацию; остальные параметры оставьте на месте.

services:
  holkas:
    environment:
      HolkasWeb__Retention__Days: "90"

Для docker run добавьте -e HolkasWeb__Retention__Days=90 при создании контейнера. В Windows перед запуском выполните $env:HolkasWeb__Retention__Days = "90" в том же окне PowerShell.

Вы изменили конфигурацию того экземпляра Holkas, который используете. Пока процесс не перезапущен с новыми параметрами, срок остаётся прежним.

Примените настройки запуска

Дождитесь окончания построения и применения планов. В каталоге Compose выполните команды: Docker пересоздаст сервис с изменённым окружением и подключит прежний том.

docker compose up -d holkas
docker compose logs --tail 50 holkas

Простой docker restart или docker compose restart не подхватит новые переменные из файла Compose. Для docker run контейнер нужно пересоздать с прежними настройками и новым -e. В Windows остановите Holkas через Ctrl+C и запустите заново из окна или сценария с заданными переменными.

В журнале есть адрес Now listening on. Прежний вход работает, список ваших подключений сохранился.

Проверьте фактическое значение

Откройте «Обслуживание» → «Хранение». В строке «Груз живёт после завершения» должно быть 90 дн.. Здесь видно, что реально использует сервер, а не только что записано в вашем файле.

Карточка Хранение с применённым сроком 90 дней
Реальный экземпляр Holkas после изменения параметра и пересоздания контейнера. Срок — 90 дней, последние 20 операций сохраняют файлы независимо от возраста.

Значение изменилось на 90 дней. Для этой проверки нажимать «Очистить сейчас» не требуется.

Найдите свою настройку

ЗадачаЧто менятьКак проверить
Открывать Docker-установку на другом портуВнешнюю часть ports, например 127.0.0.1:8081:8080Открыть localhost:8081; внутри контейнера остаётся порт 8080
Изменить адрес или порт WindowsASPNETCORE_URLS, например http://localhost:5080Адрес в журнале запуска и открытие его в браузере
Хранить файлы операций дольшеHolkasWeb__Retention__Days«Обслуживание» → «Хранение»
Перенести данные на другой дискСкопировать остановленный экземпляр; затем изменить пути или подключённый томВ журнале указан ожидаемый путь; прежние подключения и вход доступны
Выключить автоматическую проверку выпусковHolkasWeb__Updates__Enabled=false или настройку в «Обслуживании»Карточка «Обновления» показывает выключенную проверку
Задать первого администратора до открытия портаHolkasWeb__BootstrapAdminPassword на чистой установкеОбычный вход с admin вместо экрана создания пароля
Работать на своей машине без входаРежим Local, доступ только с этой машиныРабочий интерфейс открывается без формы входа
Использовать корпоративный SSOРежим Team, Keycloak и HTTPSВход через кнопку «Войти через Keycloak»

Порт и пути без потери данных

В Docker публикация 8081:8080 означает «порт машины → порт контейнера». Чтобы поменять только адрес в браузере, меняйте левую часть. ASPNETCORE_URLS меняет слушатель внутри контейнера; при его изменении придётся согласовать и правую часть публикации.

В Windows переменные действуют для программы, запущенной из того же окна PowerShell:

$env:ASPNETCORE_URLS = 'http://localhost:5080'
$env:HolkasWeb__Retention__Days = '90'
& 'C:\Holkas\holkas-web-win-x64\Holkas.Web.exe'

Присвоение HolkasWeb__DataPath не переносит файлы. Сначала остановите Holkas и скопируйте полный каталог, затем поменяйте путь. Если задан HolkasWeb__StatePath, база SQLite остаётся по этому отдельному адресу. В Docker-образе он уже задан как /data/holkasweb.db: при смене внутреннего каталога меняйте оба пути. Обычно проще оставить /data внутри и заменить только источник его монтирования.

Если StatePath или TeamAuth__KeysDirectory указывают за пределы DataPath, включите эти места в резервную копию. Новый пустой каталог выглядит как новая установка: прежние данные от этого не исчезают, но Holkas их не видит.

Основные

ПеременнаяНазначениеПо умолчанию
HolkasWeb__ModeРежим работы: Standalone, Local или Team (см. ниже)Standalone
HolkasWeb__BootstrapAdminPasswordПароль пользователя admin, который создаётся при первом старте, если в базе ещё нет пользователей. После этого переменная не читаетсяне задан
HolkasWeb__DataPathКаталог данных: файлы операций, журналы, ключи Data Protection, ключи подписи токенов/data в Docker-образе; без него — %LOCALAPPDATA%\Holkas на Windows, ~/.local/share/Holkas на Linux
HolkasWeb__StatePathФайл базы состояния SQLite: подключения, пользователи, история операцийВ образе Docker явно задан /data/holkasweb.db; вне образа — holkasweb.db в каталоге данных
ASPNETCORE_URLSАдреса и порты, на которых Holkas принимает HTTPDocker — http://+:8080; Windows — http://localhost:5000

В режиме Standalone пароль администратора не встроен в образ. Если переменная не задана, при первом открытии Holkas попросит задать пароль в браузере — не короче 8 символов, с повторным вводом. Код из журнала запуска не требуется. До создания администратора это может сделать любой, кому доступен Holkas по сети; для серверной установки задайте HolkasWeb__BootstrapAdminPassword заранее. В режиме Team без переменной создаётся admin с паролем admin — смените его сразу после входа. Для уже созданного admin переменная ничего не меняет, пароль меняется в интерфейсе.

В сборке для Windows без переменных приложение стартует в режиме Standalone, данные хранит в %LOCALAPPDATA%\Holkas — вне каталога программы, так что обновление их не трогает, — и слушает http://localhost:5000. Если рядом с программой остался каталог holkas-data от прежних версий, при первом старте Holkas копирует его в новое место.

Режимы работы

Способ входа задаётся при запуске переменной HolkasWeb__Mode. Он не зависит от установки в Docker или Windows. Сравнение трёх вариантов поможет выбрать режим.

Standalone — логин и пароль

Режим по умолчанию, для личной установки и небольшой команды. Пользователи, группы и права хранятся в базе состояния Holkas. На чистой установке создайте пароль admin, затем отдельные учётные записи коллег. Токены для CLI и агентов выдаются в интерфейсе.

Именно этот путь показан в инструкциях Docker и Windows. Явное значение режима — HolkasWeb__Mode=Standalone.

Local — работа без входа

В Local форма входа не нужна: любой, кто может обратиться к серверу Holkas, работает с правами администратора. Это вариант для локальной работы на своей машине. Оставьте доступ только с этой машины; не публикуйте такой экземпляр в сеть и не направляйте к нему внешний прокси.

Docker. В команду запуска добавьте -e HolkasWeb__Mode=Local перед именем образа belousov2501/holkas:latest. Сохраните привязку порта -p 127.0.0.1:8080:8080. Режим начинает действовать при создании контейнера; для уже работающего экземпляра нужно пересоздание с прежним томом, простой docker restart окружение не меняет.

Windows. Остановите работающий Holkas и запустите его из PowerShell с параметрами:

$env:HolkasWeb__Mode = 'Local'
$env:ASPNETCORE_URLS = 'http://localhost:5000'
& 'C:\Holkas\holkas-web-win-x64\Holkas.Web.exe'

Замените путь к программе своим. Переменные действуют в этом окне PowerShell и запущенном из него процессе.

Проверка: откройте http://localhost:8080 для Docker или http://localhost:5000 для Windows в приватном окне браузера. Рабочий интерфейс должен открыться без запроса логина и пароля. Имя, под которым пишется история, задаёт HolkasWeb__LocalUserName (по умолчанию local); отдельных участников Local не различает.

Чтобы вернуть вход по паролю, задайте HolkasWeb__Mode=Standalone и перезапустите программу с новой конфигурацией; в Docker пересоздайте контейнер. Если учётная запись Holkas уже была создана, используйте её прежний пароль. Если пользователей ещё нет, при первом открытии задайте пароль администратора или передайте его через HolkasWeb__BootstrapAdminPassword до запуска. Вход без пароля не отменяет учётных данных и прав, нужных самому серверу для подключения к PostgreSQL или Oracle.

Team — корпоративный SSO

Люди входят через Keycloak. Для команды администратор настраивает HTTPS, клиента Keycloak и группы доступа; одного HolkasWeb__Mode=Team недостаточно. Параметры и порядок входа приведены ниже. Для MCP-агентов Holkas выдаёт собственные OAuth-токены — это продолжает тот же корпоративный вход.

Политика хранения

При очистке завершённая операция остаётся в журнале: кто, когда, откуда куда, чем кончилось. Срок жизни получает только её груз — план, файл журнала, входные и выходные файлы. Чистка проходит при старте и затем по таймеру, пока система работает; карточка «Обслуживание» в интерфейсе показывает, что подлежит удалению, и позволяет запустить проход вручную даже при выключенной политике.

ПеременнаяНазначениеПо умолчанию
HolkasWeb__Retention__EnabledВключает автоматическую чистку. false — выключить фоновую чисткуtrue
HolkasWeb__Retention__DaysСколько дней после завершения операции живут её план, журнал и файлы30
HolkasWeb__Retention__AlwaysKeepLastСтолько последних завершённых операций сохраняют груз независимо от возраста20
HolkasWeb__Retention__OrphanUploadHoursЧерез сколько часов удаляются загруженные файлы, не ставшие входом ни одной операции24
HolkasWeb__Retention__SweepIntervalHoursПериод между проходами чистки24

Срок применяется после завершения операции. Последние AlwaysKeepLast операций сохраняют файлы независимо от возраста: при значении 20 на небольшой установке удалять может быть нечего даже через 90 дней. Увеличение срока не восстанавливает уже удалённые файлы.

Параметры ограничиваются автоматически: Days — 1–3650, AlwaysKeepLast — 0–10000, OrphanUploadHours — 1–8760, SweepIntervalHours — 1–720. Карточка «Хранение» показывает уже применённые значения. Кнопка «Очистить сейчас» запускает ручной проход и при выключенной автоматической чистке.

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

Построение плана

ПеременнаяНазначениеПо умолчанию
HolkasWeb__Operations__PlanBuildTimeoutСколько может идти построение плана. Если за это время план не построен, построение останавливается, операция получает статус Failed, а в ошибке указан этап и последний обработанный объект. 00:00:00 снимает ограничение00:30:00
HolkasWeb__Operations__StallNoticeЧерез сколько времени без продвижения журнал операции пишет, на каком этапе и после какого объекта Holkas ждёт ответа базы. 00:00:00 отключает такие записи00:02:00

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

Проверка новых версий

ПеременнаяНазначениеПо умолчанию
HolkasWeb__Updates__EnabledРазрешает проверять наличие новых версий через Aviso. false запрещает проверку, в том числе её включение из интерфейсаtrue
HolkasWeb__Updates__UrlАдрес продукта для проверки версий; задаётся независимо от адреса поддержкиhttps://aviso.belousov.net.ru/holkas

Если запуск разрешает проверку, администратор может выключить её в «Обслуживании»; это решение сохраняется в базе. Включение пускового параметра обратно не отменяет выключение в интерфейсе. Проверка лишь сообщает о выпуске — сама программу не устанавливает. Какие сведения передаются и как обновиться.

Поддержка

Страница Поддержка отправляет обращения в Aviso: каждый пользователь один раз привязывает свою почту кодом из письма, дальше обращения уходят от его имени — из интерфейса и через его агента. Для этого серверу Holkas нужен выход к адресу поддержки; без него обращение выгружается в файл, который форма Aviso загружает с другого устройства.

ПеременнаяНазначениеПо умолчанию
HolkasWeb__Support__UrlСтраница продукта в Aviso. Можно указать свою установку Aviso; пустое значение выключает обращения из Holkashttps://aviso.belousov.net.ru/holkas
HolkasWeb__Support__ShowDeveloperLinkПри заменённом адресе оставлять в «О системе» ссылку «Сообщить разработчику Holkas»true
HolkasWeb__Support__InstanceNameИмя установки в подписи подключения, которую человек видит в своём кабинете Avisoимя машины

Режим Team

Пароль первого администратора. В режиме Team при первом запуске создаётся пользователь admin с паролем admin, если не задан HolkasWeb__BootstrapAdminPassword. Задайте переменную до первого запуска или смените пароль сразу после входа.

Это настройки корпоративного SSO через Keycloak; они читаются только при HolkasWeb__Mode=Team. Holkas выступает клиентом Keycloak для входа людей и собственным сервером авторизации для MCP-агентов.

Что подготовить администратору: публичный HTTPS-адрес Holkas, realm и клиент в Keycloak с адресом возврата {Issuer}/signin-oidc, передачу групп в claim groups и членство пользователей в группах с нужным префиксом. Для обычных участников затем задайте права на подключения в Holkas. Переменные ниже передаются при запуске; значения адресов в таблице — примеры.

Как войти пользователю: откройте адрес Holkas, нажмите «Войти через Keycloak» и пройдите корпоративный вход. После возврата в Holkas будет создана или обновлена ваша учётная запись и членство во внешних группах. Отдельный пароль Holkas для этого не требуется. Внешними группами управляют в Keycloak; без группы с префиксом holkas_ (или настроенным GroupPrefix) Holkas откажет во входе.

Локальная учётная запись с паролем в Team тоже доступна через ту же страницу входа. Она не объединяется автоматически с корпоративной записью, даже если совпадает имя. Для подключения агента через OAuth используется корпоративный вход в браузере.

ПеременнаяНазначениеПо умолчанию
TeamAuth__IssuerПубличный адрес этого экземпляра Holkas, как его видят браузеры и агенты: https://holkas.example.org. Обязателен—
TeamAuth__KeycloakAuthorityАдрес realm Keycloak, которому делегируется вход: https://auth.example.org/realms/team. Обязателен—
TeamAuth__KeycloakClientIdКлиент Keycloak, от имени которого Holkas выполняет вход (Authorization Code + PKCE, редирект на {Issuer}/signin-oidc). Клиенту нужен маппер групп в claim groups. Обязателен—
TeamAuth__KeycloakClientSecretСекрет клиента, если он конфиденциальныйне задан — публичный клиент
TeamAuth__GroupPrefixВ Holkas попадают только группы Keycloak с этим префиксом; пользователь без таких групп не пропускаетсяholkas_
TeamAuth__AdminGroupГруппа, участники которой — администраторы Holkasholkas_admins
TeamAuth__Scopes__0Области, которые Holkas выдаёт MCP-агентамmcp
TeamAuth__RequireHttpsMetadatafalse разрешает Keycloak по обычному HTTP — только для стенда за проксиtrue
TeamAuth__KeysDirectoryГде лежат сертификаты подписи и шифрования токенов; без них перезапуск обесценил бы выданные токеныkeys внутри HolkasWeb__DataPath

Журналирование

Уровень журнала приложения задаётся стандартными ключами .NET: Logging__LogLevel__Default (Information по умолчанию), Logging__LogLevel__Microsoft.AspNetCore (Warning). Подробный журнал отдельной операции включается не здесь, а галочкой «Подробный лог» при её запуске.

Если настройка не применилась

СимптомЧто проверить
После правки Compose осталось прежнее значениеВыполнен ли docker compose up -d holkas, а не только restart; изменён ли файл нужного проекта
В Windows новая настройка не появиласьПрограмма должна быть запущена из того же PowerShell, где заданы $env:…, или из соответствующего сценария
Пароль из переменной не подходитBootstrap действует только при создании первого пользователя; существующий пароль меняется в интерфейсе
В браузере «Первый запуск» вместо прежних данныхСверьте том, DataPath, StatePath и пользователя Windows; не продолжайте с пустой установкой вместо прежней
Старые файлы не исчезают после срокаПроверьте AlwaysKeepLast, возраст после завершения и время следующего прохода; в «Хранении» видно, что подлежит удалению
Папка данных перенесена, но вход или чтение настроек сломалисьВосстановите полный набор данных и исходные ключи; сверьтесь с инструкцией восстановления