Deconflictor

Развёртывание Deconflictor в компании

Deconflictor принимает изменения через веб-интерфейс, API и нормализованные вебхуки, сопоставляет их окна с графом зависимостей и сохраняет решение с проверяемыми основаниями. Это прототип: одна компания, одна БД и один процесс приложения на установку. Для начала используйте режим рекомендаций advisory; решение о выпуске принимает ваша интеграция.

Английская версия. Контракт API: OpenAPI. В вашей установке интерактивный справочник Swagger находится на /docs, схема — на /openapi.json. Публичная копия справочника не отправляет запросы в установки компаний.

Подготовка

Нужны Docker Engine с Compose v2, доступ к выданному исходному коду или согласованному образу, HTTPS-прокси и доступ к выбранной модели. Команды ниже выполняются в корне репозитория. Образ собирается для Linux; базовые образы и зависимости закреплены в исходном коде. Подберите ресурсы по своему объёму заявок и нагрузке: универсальной гарантии пропускной способности нет. Приложение оценивает заявки последовательно и сохраняет заявки и решения в PostgreSQL. Очередь worker находится в памяти; незавершённые оценки восстанавливаются из БД.

Подготовьте каталог deployment/ с двумя файлами: catalog-info.yaml и policy.yaml. В каталоге Backstage используйте устойчивые имена Component и Resource; ребро frontend → database означает «frontend зависит от database». Начните с примера каталога, заменив его сервисами компании. Внешние Location рекурсивно не загружаются; доставку свежего файла из вашей CMDB или Backstage настраивает администратор.

Возьмите пример политики и замените поверхности и окна. Без ограничений файл содержит:

blackouts: []
maintenance_windows: []

Повтор неизменённого импорта не меняет граф. Приложение отказывается работать с пустым каталогом. Текущий предел Intake — 300 поверхностей; до подключения более крупной области проверьте полноту графа и ограничения прототипа. Разделение установок не должно скрывать межсервисные зависимости.

Установка с ключом API

Это обычный вариант автоматизации. Используйте отдельный ключ провайдера с контролем расходов.

cp production.env.example .env.production
openssl rand -hex 32
openssl rand -hex 32
chmod 600 .env.production

Два случайных значения задайте в .env.production как POSTGRES_PASSWORD и DECONFLICTOR_API_TOKEN. Они должны различаться. Не сохраняйте их в истории команд, репозитории, заявках или снимках экрана. Заполните:

DECONFLICTOR_LLM_ADAPTER=api
DECONFLICTOR_AGENT_MODEL=openai:MODEL_ID
DECONFLICTOR_AGENT_EFFORT=medium
DECONFLICTOR_EXPLAIN_LANGUAGE=ru
DECONFLICTOR_MODE=advisory
OPENAI_API_KEY=

Вместо MODEL_ID укажите доступную вашему API-аккаунту модель со структурированными ответами, а в OPENAI_API_KEY — ключ. Название модели API не обязано совпадать с названием в подписке. Для совместимого шлюза задайте DECONFLICTOR_API_OPENAI_BASE_URL; сначала проверьте поддержку JSON-схем и выбранного effort. Другие модели по ролям задаются через DECONFLICTOR_INTAKE_MODEL, DECONFLICTOR_JUDGE_MODEL, DECONFLICTOR_CHALLENGER_MODEL, DECONFLICTOR_CHAIR_MODEL и соответствующие переменные *_EFFORT.

docker compose --env-file .env.production -f compose.production.yaml up --build -d --wait

Сервис setup применяет миграции и импортирует каталог, затем запускается app. PostgreSQL хранится в томе pgdata и не публикует порт. Приложение доступно с хоста по http://127.0.0.1:8000; DECONFLICTOR_PORT меняет этот порт.

Установка с подпиской Codex

Этот вариант использует выделенную организацией учётную запись подписки. Её квота общая с другими сеансами аккаунта; доступность модели и условия подписки проверяет администратор. Ключ API не требуется. В .env.production задайте:

DECONFLICTOR_LLM_ADAPTER=codex_cli
DECONFLICTOR_AGENT_MODEL=gpt-6-astra
DECONFLICTOR_AGENT_EFFORT=medium
OPENAI_API_KEY=

Названия моделей Codex пишутся без префикса openai:. Во всех командах этого варианта добавляйте -f compose.codex.yaml после -f compose.production.yaml:

docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml build app codex-auth
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml run --rm --no-deps codex-auth
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml up --build -d --wait

Команда входа показывает адрес и одноразовый код: подтвердите вход в браузере разрешённой учётной записью. Вход по коду устройства должен быть разрешён в настройках аккаунта. Не передавайте код в журналы общего доступа. Состояние входа хранится в отдельном томе codex-home, доступном процессу UID 10001 для обновления сессии. Это секрет, не обычный кэш. Приложение запускает закреплённую версию CLI внутри своего контейнера, без Docker socket, с отключёнными инструментами и пользовательской конфигурацией. Переключения на API при ошибке входа нет.

docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml run --rm --no-deps codex-auth python -m deconflictor.api.codex status

Для повторного входа остановите только app, выполните команду входа и снова запустите up -d --wait. Для выхода после остановки приложения замените status на logout. Статус входа проверяется локально; истёкшая серверная сессия может обнаружиться только при запросе модели. Документация OpenAI по авторизации.

Подробный контракт настройки моделей описывает версии CLI, окружение процесса и хранение входа.

HTTPS, доступ и первая проверка

Перед приложением нужен корпоративный обратный прокси с HTTPS. Веб-интерфейс и /api обслуживаются с одного адреса. Для событий SSE отключите буферизацию и разрешите долгие соединения. Запускайте один экземпляр приложения: очередь и уведомления координируются внутри процесса. DECONFLICTOR_FORWARDED_ALLOW_IPS должен перечислять только доверенные адреса прокси; по умолчанию эти заголовки игнорируются.

В браузере откройте адрес установки и введите API-токен. В Swagger нажмите Authorize и введите только токен, без слова Bearer. Справочник загружает все ресурсы локально, не использует внешнюю проверку схем и не сохраняет этот токен после обновления страницы. Прототип использует один общий токен: персональных ролей, SSO и изоляции арендаторов внутри установки нет. Корпоративные ограничения доступа настройте на прокси.

Проверьте GET /api/info: llm.answers должно быть live, llm.adapter — api или codex_cli, а graph_version — ненулевым. Затем отправьте одну безопасную заявку команды и дождитесь решения с обоснованием. Это реальный расход API или квоты подписки. Успешный запуск проверяет настройки и БД, но не баланс и доступность провайдера.

Интеграция CI/CD и тикетов

Для повторяемой доставки используйте POST /api/integrations/changes с заголовками Authorization: Bearer <token> и Content-Type: application/json. Это нормализованный входящий вебхук: ваша автоматизация переводит поля исходного CI или тикета в эту схему. Сырые события конкретного вендора и его подпись этим маршрутом не интерпретируются.

{
  "source": "ci-checkout",
  "external_id": "checkout/deploy/8142",
  "change": {
    "title": "Обновление checkout",
    "body": "Поэтапно обновляем checkout; запись остаётся доступной.",
    "kind": "deploy",
    "author": "team-checkout",
    "environment": "prod",
    "window": {"start": "2026-10-14T08:00:00Z", "end": "2026-10-14T08:30:00Z"},
    "declared_surfaces": ["component:default/checkout"],
    "links": ["https://issues.example.org/releases/8142"]
  }
}

Замените дату и имя сервиса. Все даты требуют часового пояса; окно включает начало и не включает конец. source — постоянное имя интеграции, external_id — неизменная ревизия выпуска или тикета, а не номер попытки доставки. Повтор того же содержимого с той же парой ключей возвращает 200 и тот же UUID; первый приём — 202. Другое содержимое с тем же ключом даёт 409 external_identity_conflict. Для нового плана нужна новая ревизия, старую отмените. После таймаута повторите то же тело либо найдите заявку через GET /api/integrations/changes?source=ci-checkout&external_id=checkout/deploy/8142.

Ответ подтверждает сохранение. Для автоматического разрешения выпуска интеграция должна заново прочитать карточку по card и проверить все условия:

  • status=active и evaluation.state=done.
  • record и outcome существуют; record.id=outcome.record_id и record.content_version=content_version.
  • record.final_verdict=outcome.final_verdict=approve.
  • record.chair.status — ok или carried. not_asked и skipped_standard допустимы только по явной политике компании.
  • Нет действующего override: ручное несогласие требует отдельного процесса согласования компании и не меняет вердикт сервиса.

При pending дождитесь объяснения и прочитайте карточку повторно: председатель может ужесточить разрешение до эскалации. failed, неизвестный статус Chair, reject, escalate, ошибка оценки, таймаут и неполный ответ не разрешают автоматический выпуск. Ограничьте время ожидания; ошибки передавайте человеку. Повтор webhook восстанавливает только отсутствующую первоначальную оценку, а не повторяет ожидающий или неудачный Chair.

Повторно прочитайте карточку непосредственно перед выпуском: другие заявки или действия могут изменить решение. Чтение API не блокирует календарь и не выдаёт атомарного разрешения на внешний запуск; сервис сам не развёртывает изменения. Полные правила доставки и примеры интеграций хранятся вместе с кодом.

Обычный POST /api/changes также доступен: UUID можно передать самим, но повтор UUID возвращает конфликт. Изменения принимаются через веб-форму, без внешней интеграции. После отмены или исполнения отправьте PATCH /api/changes/{id}/status со значением withdrawn или executed; связанные решения пересчитаются. Deconflictor не выполняет само развёртывание. Человеческое переопределение с причиной хранит несогласие в истории, но не меняет решение кода. Перенос окна принимает только предложение из актуальной карточки.

События доступны по events и /api/events. Для продолжения передайте Last-Event-ID с последним полученным seq. Браузерный EventSource допускает параметр access_token; уберите этот параметр из журналов прокси. Для других клиентов используйте заголовок. Исходящие уведомления отдельно настраиваются через DECONFLICTOR_NOTIFY_WEBHOOK_URL; это не адрес приёма входящих заявок.

Безопасность и хранение

Тексты заявок, сведения о сервисах и цитаты передаются выбранной модели. Согласуйте разрешённые данные, условия провайдера и сроки хранения до подключения внутренних проектов. Запросы и обоснования остаются в PostgreSQL; автоматической политики удаления сейчас нет. Не передавайте в описаниях пароли, ключи и персональные данные без необходимости.

Ограничьте сеть БД, доступ к хосту, исходящие адреса модели и право чтения .env.production. Шифруйте диски и резервные копии средствами инфраструктуры. Приложение работает без root, с кодом только для чтения. Проверьте журналы прокси на токены в URL. При утечке общего API-токена замените его в конфигурации, пересоздайте app и обновите доверенные клиенты. Для Codex отдельно отзовите вход и войдите снова; не копируйте codex-home в обычные архивы.

Резервные копии и восстановление

Сохраняйте дамп БД, точную версию приложения, каталог и политику. Секреты храните отдельно. Для Codex добавляйте второй Compose-файл во все команды, как выше.

docker compose --env-file .env.production -f compose.production.yaml exec -T db pg_dump -U deconflictor -d deconflictor -Fc > backup.dump

Проверяйте восстановление в отдельной установке той же версии с новым пустым томом БД: поднимите только db, дождитесь его готовности, затем импортируйте дамп. Не запускайте setup до восстановления, иначе новая БД уже будет содержать таблицы. В отдельной копии исходников задайте DECONFLICTOR_PORT=8001 и DECONFLICTOR_API_RESUME=0 в своём .env.production, чтобы не занять рабочий порт и не оценивать восстановленные заявки автоматически. Отдельное имя проекта Compose ниже изолирует тома. Для Codex выполните новый вход в этом проекте до запуска приложения.

docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml up -d --wait db
docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml exec -T db pg_restore --exit-on-error --no-owner -U deconflictor -d deconflictor < backup.dump
docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml up -d --wait

Сверьте граф, количество заявок, историю и одну карточку. Для подписки выполните новый вход в отдельной установке. Не используйте down -v для штатной остановки: это удаляет данные.

Обновление и изменение каталога

Сначала сохраните резервную копию и версии конфигурации. Остановите app, получите проверенную версию исходников/образа и пересоздайте setup для миграций перед запуском:

docker compose --env-file .env.production -f compose.production.yaml stop app
docker compose --env-file .env.production -f compose.production.yaml build
docker compose --env-file .env.production -f compose.production.yaml up --force-recreate --no-deps --exit-code-from setup setup
docker compose --env-file .env.production -f compose.production.yaml up -d --wait

При ошибке миграции не запускайте новую версию приложения. Откат кода не откатывает схему: восстанавливайте проверенный дамп в отдельную БД вместе с прежней версией приложения. После успешного обновления проверьте /api/info, журнал setup и тестовую заявку.

Для обновления каталога замените файл и выполните импорт без вызова модели:

docker compose --env-file .env.production -f compose.production.yaml run --rm --no-deps setup deconflictor graph import /config/catalog-info.yaml

После изменения политики пересоздайте app. Старые Decision Record сохраняют прежнюю версию графа, политики и сведения о моделях; история не переписывается.

Поиск неисправностей

docker compose --env-file .env.production -f compose.production.yaml ps
docker compose --env-file .env.production -f compose.production.yaml logs --tail=100 app setup
  • 401: проверьте токен приложения и клиента; в Swagger вводится только значение токена.
  • 403: приложение запущено без токена и запрещает внешние запросы; не обходите эту проверку заголовками.
  • 409: прочитайте код ошибки; повтор вебхука с другим телом требует новой ревизии, устаревшая карточка — повторного чтения.
  • 422: ответ содержит все нарушения с полями; проверьте часовой пояс, окно и канонические имена поверхностей.
  • 503: проверьте готовность БД, миграции и конфигурацию сервиса.
  • Оценка failed: найдите причину в карточке и журнале; исправьте ключ, вход или лимит модели. Перезапуск по умолчанию восстанавливает незавершённые оценки.
  • Нет событий: проверьте буферизацию и таймаут прокси, токен, последний seq; повторное подключение продолжает поток.
  • Неизвестный сервис: проверьте /api/surfaces и импорт каталога; имя в заявке должно совпадать с каноническим ref или его алиасом.

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

Исходник руководства

Deploying Deconflictor in your company

Deconflictor receives changes through its web UI, API and normalized webhooks, compares their windows against the dependency graph and stores a decision with verifiable evidence. This is a prototype: one company, one database and one application process per installation. Start in advisory mode; your integration owns the release decision.

Russian version. API contract: OpenAPI. Interactive Swagger documentation is available at /docs in your installation, with the schema at /openapi.json. The public reference cannot send requests to company installations.

Prerequisites

You need Docker Engine with Compose v2, access to the supplied source release or an agreed image, an HTTPS reverse proxy and access to your chosen model. Run the commands below from the repository root. Images target Linux; base images and dependencies are pinned in source. Size the installation against your own request volume and load: there is no universal throughput guarantee. The application evaluates requests serially and stores requests and decisions in PostgreSQL. The worker queue is in memory; unfinished evaluations are recovered from the database.

Create deployment/ containing catalog-info.yaml and policy.yaml. In your Backstage catalog, use stable Component and Resource names. The edge frontend → database means that frontend depends on database. Adapt the catalog example to your company. External Location documents are not recursively fetched; the administrator must deliver an updated file from the CMDB or Backstage.

Adapt the surfaces and windows in the policy example. For an installation without policy restrictions, use:

blackouts: []
maintenance_windows: []

An unchanged import does not change the graph. The application refuses to run with an empty catalog. Intake currently supports up to 300 surfaces; assess graph completeness and prototype limits before connecting a larger area. Splitting installations must not hide dependencies between services.

Install with an API key

This is the usual automation option. Use a dedicated provider key with spending controls.

cp production.env.example .env.production
openssl rand -hex 32
openssl rand -hex 32
chmod 600 .env.production

Put the two different random values into .env.production as POSTGRES_PASSWORD and DECONFLICTOR_API_TOKEN. Keep them out of command history, repositories, change descriptions and screenshots. Configure:

DECONFLICTOR_LLM_ADAPTER=api
DECONFLICTOR_AGENT_MODEL=openai:MODEL_ID
DECONFLICTOR_AGENT_EFFORT=medium
DECONFLICTOR_EXPLAIN_LANGUAGE=en
DECONFLICTOR_MODE=advisory
OPENAI_API_KEY=

Replace MODEL_ID with a model available to your API account that supports structured answers, and put the key in OPENAI_API_KEY. An API model name need not match a subscription model name. For a compatible gateway set DECONFLICTOR_API_OPENAI_BASE_URL; first check support for JSON schemas and the selected effort. Override individual roles with DECONFLICTOR_INTAKE_MODEL, DECONFLICTOR_JUDGE_MODEL, DECONFLICTOR_CHALLENGER_MODEL, DECONFLICTOR_CHAIR_MODEL and the corresponding *_EFFORT variables.

docker compose --env-file .env.production -f compose.production.yaml up --build -d --wait

setup applies database migrations and imports your catalog before app starts. PostgreSQL uses the persistent pgdata volume and publishes no port. The application is available on the host at http://127.0.0.1:8000; change the host port with DECONFLICTOR_PORT.

Install with a Codex subscription

This option uses a subscription identity assigned by your organization. Its quota is shared with other sessions on that account; the administrator checks model access and subscription terms. No API key is needed. Set in .env.production:

DECONFLICTOR_LLM_ADAPTER=codex_cli
DECONFLICTOR_AGENT_MODEL=gpt-6-astra
DECONFLICTOR_AGENT_EFFORT=medium
OPENAI_API_KEY=

Codex model names have no openai: prefix. For every command in this deployment, add -f compose.codex.yaml after -f compose.production.yaml:

docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml build app codex-auth
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml run --rm --no-deps codex-auth
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml up --build -d --wait

The login command prints a URL and a one-time code. Complete the login in your browser with the approved identity. Device-code login must be enabled in the account settings. Do not publish the code in shared logs. Login state lives in the separate codex-home volume, writable by UID 10001 for session refresh. Treat it as a secret, not an ordinary cache. The application runs a pinned CLI inside its own container, without a Docker socket, with tools and user configuration disabled. Login errors never cause a fallback to the API.

docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml run --rm --no-deps codex-auth python -m deconflictor.api.codex status

To renew login, stop only app, run the login command and start it with up -d --wait again. To log out, stop the application first and replace status with logout. Login status is a local check; an expired server-side session may only be discovered when making a model request. See OpenAI authentication documentation.

The detailed model configuration contract covers CLI versions, process environment and login storage.

HTTPS, access and first verification

Put a corporate HTTPS reverse proxy in front of the application. Keep the web UI and /api on the same origin. Disable response buffering and allow long connections for SSE. Run one application instance: queue and notification coordination live inside that process. DECONFLICTOR_FORWARDED_ALLOW_IPS must list only trusted proxy addresses; forwarded headers are ignored by default.

Open the installation in your browser and enter its API token. In Swagger select Authorize and enter just the value, without the word Bearer. Documentation loads its assets locally, uses no remote schema validator and does not retain this token after a page reload. The prototype has one shared token and no built-in individual roles, SSO or tenant isolation. Enforce corporate access restrictions at the proxy.

Check GET /api/info: llm.answers must be live, llm.adapter must be api or codex_cli, and graph_version must be non-zero. Submit one safe team-owned request and wait for its decision and explanation. This consumes real API spend or subscription quota. Successful startup checks settings and the database, but does not establish provider balance or availability.

Integrate CI/CD and tickets

For repeatable delivery use POST /api/integrations/changes with Authorization: Bearer <token> and Content-Type: application/json. This is a normalized incoming webhook: your automation maps the CI or ticket fields into this schema. The route does not interpret a vendor's raw event format or verify its native signature.

{
  "source": "ci-checkout",
  "external_id": "checkout/deploy/8142",
  "change": {
    "title": "Roll out checkout v2",
    "body": "Restart checkout replicas one at a time; writes remain available.",
    "kind": "deploy",
    "author": "team-checkout",
    "environment": "prod",
    "window": {"start": "2026-10-14T08:00:00Z", "end": "2026-10-14T08:30:00Z"},
    "declared_surfaces": ["component:default/checkout"],
    "links": ["https://issues.example.org/releases/8142"]
  }
}

Replace the dates and surface. Every timestamp requires a timezone; windows include their start and exclude their end. source is a stable integration namespace; external_id is an immutable rollout or ticket revision, not a delivery attempt number. Identical content and identity return 200 with the same UUID on retry; the first acceptance returns 202. Changed content under the same identity produces 409 external_identity_conflict. A new plan needs a new revision; withdraw the old change. After a timeout resend the same body or look it up with GET /api/integrations/changes?source=ci-checkout&external_id=checkout/deploy/8142.

Acceptance confirms storage. Before permitting an automatic release, the integration must read the current card from card and verify every condition:

  • status=active and evaluation.state=done.
  • Both record and outcome exist; record.id=outcome.record_id and record.content_version=content_version.
  • record.final_verdict=outcome.final_verdict=approve.
  • record.chair.status is ok or carried. Accept not_asked and skipped_standard only under explicit company policy.
  • There is no current override: human disagreement requires the company's separate approval process and does not replace the service verdict.

When pending, wait for the explanation and read the card again: the Chair can tighten approval to escalation. Failed or unknown Chair status, rejection, escalation, evaluation errors, timeouts and incomplete responses never permit automatic release. Set a finite wait and require human follow-up on errors. Retrying a webhook only recovers a missing initial evaluation; it does not retry a pending or failed Chair.

Read the card again immediately before releasing: other submissions or actions may change the decision. Reading the API does not lock the calendar or grant an atomic deployment permit; the service itself does not deploy. The full delivery contract and integration examples are maintained with the code.

POST /api/changes is also available. You may supply a UUID, but repeating it returns a conflict. Users can submit changes through the web form without an integration. After cancellation or execution, send PATCH /api/changes/{id}/status with withdrawn or executed; related outcomes will be recounted. Deconflictor does not execute deployments. A human override with a reason records disagreement in the audit trail but does not change the code verdict. Rescheduling only accepts a free window suggested by the current card.

Events are available at the returned events path and /api/events. Resume with Last-Event-ID set to the last received seq. Browser EventSource can use access_token; remove that query value from reverse-proxy logs. Other clients should use the header. Configure outgoing notifications separately with DECONFLICTOR_NOTIFY_WEBHOOK_URL; this is not the incoming change endpoint.

Security and retention

Request text, service information and evidence quotes are sent to the chosen model. Agree on permitted data, provider terms and retention requirements before connecting internal projects. Requests and explanations remain in PostgreSQL; automatic deletion policies are not implemented. Keep passwords, credentials and unnecessary personal data out of change descriptions.

Restrict database networking, host access, model egress and access to .env.production. Encrypt disks and backups using your infrastructure. The application runs without root and with read-only code. Check proxy logs for tokens in URLs. If the shared API token leaks, replace it in the configuration, recreate app and update trusted clients. For Codex also revoke and renew the login; do not include codex-home in ordinary archives.

Backups and recovery

Retain a database dump, the exact application version, catalog and policy. Store secrets separately. For Codex, include the second Compose file in every command as described above.

docker compose --env-file .env.production -f compose.production.yaml exec -T db pg_dump -U deconflictor -d deconflictor -Fc > backup.dump

Test recovery in a separate installation of the same version with a new empty database volume. Start only db, wait for it to become healthy, then restore the dump. Do not run setup before restoring: it would create tables in the empty database. In the separate source directory, set DECONFLICTOR_PORT=8001 and DECONFLICTOR_API_RESUME=0 in its own .env.production to avoid the production port and automatic reevaluation of restored requests. The distinct Compose project name below isolates volumes. For Codex, complete a fresh login for this project before starting the application.

docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml up -d --wait db
docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml exec -T db pg_restore --exit-on-error --no-owner -U deconflictor -d deconflictor < backup.dump
docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml up -d --wait

Compare the graph, change count, history and an individual card. For subscriptions, log in afresh in the separate installation. Do not use down -v for normal shutdown: it deletes stored data.

Upgrades and catalog changes

First save a backup and the configuration versions. Stop app, obtain the reviewed source/image version, and recreate setup so migrations complete before the new application starts:

docker compose --env-file .env.production -f compose.production.yaml stop app
docker compose --env-file .env.production -f compose.production.yaml build
docker compose --env-file .env.production -f compose.production.yaml up --force-recreate --no-deps --exit-code-from setup setup
docker compose --env-file .env.production -f compose.production.yaml up -d --wait

If a migration fails, do not start the new application. Rolling back code does not roll back its schema: restore the verified dump into a separate database with the previous application version. After a successful upgrade check /api/info, the setup log and a test change.

To update the catalog, replace its file and import it without calling a model:

docker compose --env-file .env.production -f compose.production.yaml run --rm --no-deps setup deconflictor graph import /config/catalog-info.yaml

Recreate app after policy changes. Existing Decision Records retain their original graph and policy versions and model provenance; history is not rewritten.

Troubleshooting

docker compose --env-file .env.production -f compose.production.yaml ps
docker compose --env-file .env.production -f compose.production.yaml logs --tail=100 app setup
  • 401: check the application and client tokens; Swagger takes only the token value.
  • 403: without a configured token the application refuses remote access; do not bypass it with headers.
  • 409: read the error code; changed webhook content needs a new revision, and a stale card needs another read.
  • 422: the response lists all failed checks by field; inspect timezones, windows and canonical surface refs.
  • 503: check database readiness, migrations and service configuration.
  • An evaluation is failed: inspect its card and log; fix the provider key, login or model limit. Restarting recovers unfinished evaluations by default.
  • No events: check proxy buffering and timeout, the token and last sequence; reconnecting resumes the feed.
  • Unknown service: inspect /api/surfaces and the catalog import; the request must name a canonical ref or an alias.

For support collect the application version, error time with timezone, change UUID, error code and a redacted log excerpt. Do not attach .env.production, login volume contents, a database dump containing internal requests or tokens.

Guide source