Ingotron 0.9.7 configuration reference

The installer owns the appliance baseline and the installed CLI reconciles it. The Admin UI provides the normal path for the small set of reversible settings available to operators. This document describes the installed appliance at /opt/ingotron; it is not a guide to the legacy checkout stack or docker-compose.production.yml.

Configuration ownership

The effective environment is /opt/ingotron/state/env. Its companion env.meta.json records where values came from and which command owns them. Permissions are root-only. Do not copy the repository's .env.example over this file: that example is a readable schema, not an install template.

Every setting belongs to one of four classes:

Upgrade reconciliation adds new values, renames or removes retired keys, and does not silently replace a recorded operator value. Use sudo ingotron upgrade --show-config-changes to review the proposed change set.

Open Admin → Configuration to view the four settings exposed by 0.9.7. The UI allows changes only to INGOTRON_HEALTH_TIMEOUT and TIME_INDEX_CACHE_SIZE_MB. Select Review changes, inspect the planned restart, then select Apply reviewed plan. The transaction validates the candidate, applies it to the owning service, waits for health, and restores the previous state if the health check fails. Reload the page after a stale plan or an interrupted request; do not submit the same change repeatedly while the service is recovering.

set-address and the TLS commands remain the supported transactions for their own values. Do not edit state/env or invoke raw Compose to force a change: the CLI owns the overlay order, project identity, state paths, and recovery journal. Root operators may use sudo ingotron config show, sudo ingotron config plan, or sudo ingotron config apply for the same narrow settings boundary when UI access is unavailable.

The full appliance runs on one Linux server. The Admin UI may be opened from any trusted browser, while each robot receives only the small agent. RHEL-family and Fedora hosts with SELinux Enforcing are currently refused by the installer and upgrade path until a packaged Ingotron SELinux policy exists. Never disable SELinux to bypass that refusal.

The appliance reserves numeric GID 10001 for its manager socket and mounted service files. Installation creates the system group ingotron-secrets at that GID when it is absent. Installation and manager activation refuse a conflicting group name or GID, explicit group members, or host accounts whose primary GID is 10001. Existing accounts and groups are not reassigned. Resolve the reported collision before retrying; do not add human or unrelated service accounts to this group, because membership grants access to the manager's host-control API. The numeric container identity remains 10001:10001.

Managed settings

These four settings are visible in Admin → Configuration. Two are reversibly editable; the other two are shown for awareness and are controlled by the signed release or host operator because changing them can have irreversible effects.

The UI reads a revision, creates a plan token, and requires that reviewed plan when applying. If the release, revision, or running service set changes first, the plan is rejected and the UI asks you to reload and review again. Changing the cache size recreates the query service; the UI waits for it to return before reporting success.

Appliance-owned values

Public address and OIDC

These six values are one atomic set. Change them only with:

sudo ingotron set-address https://vault.example.com:8003

The command also reconciles TLS SANs and service state. KEYCLOAK_REALM defaults to ingotron, OIDC_AUDIENCE to robot-vault, OIDC_CLIENT_ID to robot-vault-ui, OIDC_ROLE_CLAIM to roles, and scopes to openid profile email offline_access. Those bundled-realm identifiers are release inputs, not a bring-your-own-OIDC interface.

Identity and ingest policy

The appliance's robot listener uses TLS plus a per-robot bearer credential. It does not use mTLS. INGEST_AUTH_TOKEN remains a required internal/adoption value but is not a credential to distribute to new robots.

Generated secrets

The installer generates at least the following, then gives services only the credentials they need:

• POSTGRES_PASSWORD and scoped database-role passwords;
• MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, and scoped S3 secret keys;
• INGEST_AUTH_TOKEN and INGEST_PROVISIONING_TOKEN;
• the Keycloak database password and bootstrap-operator password;
• the Ed25519 dataset-signing key; and
• the appliance CA private key and listener private keys.

Keycloak passwords are mounted from root-owned files, not placed in container environment variables. The dataset signing key and CA are identities, not replaceable caches. Back them up and never paste them into diagnostics.

Network settings

Only those two ports are intended appliance endpoints. PostgreSQL, MinIO, Redis, Keycloak's internal listeners, metrics, and evaluator-only consoles stay on the private Compose network.

A public port is part of APPLIANCE_URL; do not change QUERY_HTTPS_PORT alone. Use set-address, which keeps OIDC redirects and certificates aligned. If restricting a bind address, make sure browsers and robots still use an address covered by the certificate.

Backup and upgrade behavior

A command-line upgrade --health-timeout SECONDS takes precedence over this setting for that run. The release keeps two immutable releases by default. The CLI keeps the latest three pre-upgrade backups while retaining the backup needed for previous_version; those retention counts are install metadata, not public environment overrides in 0.9.7.

Storage settings

Changing a bucket, region, or root identity after data exists is a migration, not a cosmetic environment edit. The appliance's supported 0.9.7 storage topology is its bundled MinIO. Do not point individual services at different buckets/endpoints or replace their scoped credentials by hand.

The authoritative Docker volume names are in /opt/ingotron/state/install.json, not in this environment. That distinction matters after adoption.

Export and data-governance settings

This release has no bundled PII-scrubbing backend, so it records media with raw PII state. ALLOW_UNSCRUBBED=true permits exports of that raw media. It does not mean the data was scrubbed. The 0.9.7 baseline is false; changing this policy is not a reversible Admin UI operation. Setting it to false affects export, not ingest or historical retention.

QA_MIN_SCORE uses the displayed 0 to 100 DEFECT scale. It is not a fraction: 80, not 0.8, means eighty. An invalid or non-finite value stops exporter configuration instead of silently disabling the gate.

The MCAP allowlist cannot waive camera-bearing-source inspection or the raw media gate. Approve exact digests only after independent review; do not use a wildcard or a broad prefix.

Query and cache settings

TIME_INDEX_CACHE_SIZE_MB is managed through Admin → Configuration. Its default is 512 and the accepted range is 1 to 2048 whole megabytes. Reduce it on a memory-constrained host at the cost of more index work. Applying a new value recreates the query service and waits for its health check. This is not the Keycloak JVM limit; the bundled IdP has its own release-controlled memory cap.

Garbage collection

Keep dry-run enabled until its output has been reviewed against a tested backup. In 0.9.7 it is visible in the Admin UI but not editable there. Garbage collection relies on the registry's reachability model and cannot repair a missing MinIO backup. After a database restore, post-backup objects may be unreferenced; take extra care before enabling deletion.

Demo settings

The ingotron demo profile accepts these deterministic seeder settings when they are present in the effective environment:

These change only newly generated demo content.

Removed and forbidden keys

The 0.9.7 CLI refuses or removes values that would break signed-release or installation identity:

Do not add these back to state/env. Image mirroring/air-gap operation is not a supported per-host registry override in this release.

Inspect configuration without leaking it

sudo ingotron status --json and sudo ingotron version --json are the only 0.9.7 commands with machine-readable output. Other commands explicitly refuse --json rather than emitting prose that automation might misparse.

When diagnosing configuration:

sudo ingotron status --json
sudo ingotron version --json
sudo ingotron tls status

Do not attach state/env, env.meta.json, install.json, rendered Keycloak configuration, docker inspect, private TLS files, or backups to a ticket without a deliberate secret review. Redact passwords, tokens, claim material, private keys, internal hostnames, and customer identifiers.

See Operations for safe change and recovery procedures and Security for the trust model and current limitations.

Partial upload retention in 0.9.7

Durable partial uploads use fixed chunks between 5 MiB and 8 MiB. The server retains an inactive session for seven days and checks for expired sessions every 15 minutes. These are fixed implementation limits, not editable Admin settings. Saved progress is the server-confirmed total at the last resume check, which can include chunks after a missing range.

Migration 026 and the matching new server, toolkit, robot agent, and ingest object-store policy are required. Update both the appliance and robot agent through the signed release to enable durable partial resume.