Server configuration

Environment variables for the server and Console containers, the container paths they use, and the credential file formats they read.

Environment variables

Required at deploy time

The server Compose service needs these; none has a default. A standalone Console host uses Deployment settings for separate hosts instead.

The shipped layouts also set dashboard metadata automatically: IRIS_RUNTIME_LAYOUT, IRIS_RUNTIME_NAME and IRIS_RUNTIME_HOST for Docker; IRIS_POD_NAME, IRIS_POD_NAMESPACE, IRIS_NODE_NAME and IRIS_POD_IP through the Kubernetes Downward API. These describe placement, not connection targets. For a custom combined container, declare IRIS_RUNTIME_LAYOUT=single-container. Without layout metadata or managed inventory, the dashboard reports the layout as unknown. See Deployment information.

Optional at deploy time

Use the documented bounds for each variable. 0 disables IRIS_XR_SESSION_TIMEOUT, IRIS_METRICS_PORT and API request-rate budgets; other settings may reject it or fall back to their defaults.

Origin egress addresses

When outbound origin connections use a different source address from the catalog, set IRIS_ORIGIN_EGRESS_IPS to the fixed source IPv4 addresses seen by devices. Use up to eight addresses separated by commas without spaces. For an installer-managed deployment, pass --origin-egress-ip ADDRESS to irisctl install or irisctl setup, repeating it for each address. The installer retains this selection for resume and maintenance. Confirm the addresses at a receiving device or egress gateway; a Kubernetes pod address or Service address can differ from the outbound source. Keep them stable across pod placement changes. Restricted roles that permit the origin receive these addresses in their authenticated allow-list. Peer TLS still checks the origin identity.

Container paths

server/docker-compose.yml sets each path explicitly, so a one-shot command run with docker compose exec sees the same layout as the server.

Onboarding reads the device public certificate from $IRIS_CONFIG/tls/crt.pem; IRIS_CRT_PUBLIC overrides that path. The device-side IRIS_LOG is a separate setting; see Device agent configuration.

Kubernetes maps these paths into one persistent volume under /data instead; see Data formats and states.

None of these paths is mounted into the Console. Its only server-side inputs are the public management CA and the management-credential files, read-only.

TLS trust and console certificate

The Console's Settings → TLS & trust page manages these through the management API.

The Console certificate override persists as /etc/iris/tls/gui-crt.pem plus the age-encrypted /etc/iris/tls/gui-key.pem.age; if it fails to decrypt or does not match, the Console falls back to the default identity. Public CA download settings live in $IRIS_STATE/ca-trust-settings.json.

Image path variables

The server reads images from two places; the difference decides what a delete removes and what an import offers.

The host tree behind IRIS_IMAGE_ROOT must be readable by the container's runtime user.

Telemetry variables

External telemetry is off by default. IRIS emits OpenTelemetry (OTLP); you choose the collector and backend. See Export telemetry.

SSH variables

Every SSH session the server or an installer opens verifies the peer through one shared policy:

The device agent's own SSH-to-self channel is a separate, opt-in setting; see Device agent configuration.

API admission limits

The management server can enforce one shared request budget across every Console user, session, and Console host.

Restart the server after changing any of these. Device-facing tracker, artifact, and catalog traffic is outside this limit. See Console API.

Build-time variables

These affect only how the device packages are built, not a running deployment. See Build and publish the device packages.

Deployment settings for separate hosts

Install on separate Docker hosts splits these across the server host and the Console host. Tokens and private keys stay in the provisioned files; the environment only names their directory paths.

Also set, as documented above: COMPOSE_PROJECT_NAME (both hosts), IRIS_HOST_IP and IRIS_CONSOLE_URL (server), IRIS_AGE_KEY_FILE_HOST and IRIS_AGE_RECIPIENTS (server), IRIS_IMAGE_ROOT and IRIS_ARTIFACTS_HOST_DIR (server), and IRIS_GUI_PUBLISH (Console).

The Console mounts no server state volume. A missing provisioned directory fails deployment instead of being silently created.

Credential file formats

The management and observability bearer tokens use a two-file rotation scheme, in IRIS_TIER_AUTH_DIR on a Docker host or in a Kubernetes secret:

• current (or current.json) holds the token that is checked first.
• previous (or previous.json) holds the prior token during a rotation overlap, empty before the first rotation.

Management files accept a raw token or a JSON record such as {"scope":"management","token":"<token>"}. Tokens must be at least 32 bytes long. Observability files hold the raw token value so Prometheus can read current as its credentials_file. Use distinct random values for management and observability: a raw token has no embedded scope. JSON records must match the listener's scope. See Rotate credentials and certificates and Install on Kubernetes.