Установка
Параметры запуска
Настройте вход по паролю, 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 дней. Для этой проверки нажимать «Очистить сейчас» не требуется.
Найдите свою настройку
| Задача | Что менять | Как проверить |
|---|---|---|
| Открывать Docker-установку на другом порту | Внешнюю часть ports, например 127.0.0.1:8081:8080 | Открыть localhost:8081; внутри контейнера остаётся порт 8080 |
| Изменить адрес или порт Windows | ASPNETCORE_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 принимает HTTP | Docker — 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; пустое значение выключает обращения из Holkas | https://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 | Группа, участники которой — администраторы Holkas | holkas_admins |
TeamAuth__Scopes__0 | Области, которые Holkas выдаёт MCP-агентам | mcp |
TeamAuth__RequireHttpsMetadata | false разрешает 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, возраст после завершения и время следующего прохода; в «Хранении» видно, что подлежит удалению |
| Папка данных перенесена, но вход или чтение настроек сломались | Восстановите полный набор данных и исходные ключи; сверьтесь с инструкцией восстановления |