# 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](company-deployment.md). API contract: [OpenAPI](../../openapi.json).
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](../../topologies/otel-demo-3.1.0/catalog-info.yaml)
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](../../policy.example.yaml).
For an installation without policy restrictions, use:

```yaml
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.

```sh
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:

```dotenv
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.

```sh
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`:

```dotenv
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`:

```sh
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.

```sh
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](https://developers.openai.com/codex/auth).

The detailed [model configuration contract](company-models.md) 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.

```json
{
  "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](incoming-webhooks.md)
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.

```sh
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.

```sh
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:

```sh
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:

```sh
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

```sh
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.
