Configuration

All runtime configuration is environment-driven.

The template keeps the hex-core-service variable names unchanged.

Core runtime

Expected variables include:

• SERVER_HOST
• SERVER_PORT
• LOG_LEVEL
• METRICS_ENABLED

IO adapter boundary

The template uses the current core contract directly:

• IO_ADAPTER_ID
• IO_ADAPTER_BASE_URL
• IO_ADAPTER_TIMEOUT_MS

Recommended baseline:

• IO_ADAPTER_ID=http
• IO_ADAPTER_BASE_URL points to an externally managed or separately deployed adapter

memory is a core development mode and is not part of the main deployment template path.

Authentication

Default documented path:

• AUTH_MODE=jwt_jwks

Common variables:

• AUTH_JWKS_URL
• AUTH_ISSUER
• AUTH_AUDIENCE
• AUTH_JWKS_REFRESH_SECS

Alternative modes such as forward_auth are supported by the core but are deployment variants rather than the baseline. AUTH_MODE=none is a dev-only escape hatch and should not be treated as a normal deployment mode.

Overlay intent:

• k8s/overlays/dev may use AUTH_MODE=none for local cluster bring-up
• k8s/overlays/prod uses the jwt_jwks path

Registry

Registry configuration is a first-class deployment concern.

Recommended baseline:

• REGISTRY_MODE=catalog
• REGISTRY_CATALOG_FILE=/config/registry/catalog.json
• REGISTRY_ALLOWED_HOSTS=codeberg.org
• REGISTRY_REQUIRE_HTTPS=true

The template ships a pinned local catalog file with CE-RISE model entries. Those entries use explicit artifact references such as schema_url and shacl_url rather than a single inferred base_url.

The Compose catalog (compose/registry/catalog.json) and Kubernetes catalog (k8s/base/registry-configmap.yaml) register these model versions:

Schema and SHACL URLs point to the corresponding versioned pages-v tags on Codeberg. When updating registry configuration, keep the model identifiers, versions, and artifact URLs aligned in both catalogs. HEX Core needs outbound HTTPS access to the configured artifact hosts.

Optional downstream services

The baseline template does not require any downstream application service beside hex-core-service.

RE Indicators

The re-indicators Compose profile reads these settings from compose/.env or the shell environment:

Compose maps the connection settings to HEX_CORE_BASE_URL, ARTIFACT_BASE_URL_TEMPLATE, and HTTP_TIMEOUT_SECS. Kubernetes uses these native names in the re-indicators-env ConfigMap.

SEE Impacts

The see-impacts Compose profile reads these settings from compose/.env or the shell environment:

Compose maps the prefixed variables to the service’s native variables: HEX_CORE_BASE_URL, HEX_CORE_BEARER_TOKEN, HTTP_TIMEOUT_SECS, CALCULATION_TIMEOUT_SECS, and MAX_CONCURRENT_CALCULATIONS.

The bearer token authenticates SEE’s requests to HEX Core; it does not authenticate callers of SEE. Compose publishes SEE on 127.0.0.1 only, while Kubernetes uses a ClusterIP service. Provide an authenticated reverse proxy or ingress for remote access rather than exposing SEE directly.

Kubernetes uses those native names in the see-impacts-env ConfigMap and the optional see-impacts-auth Secret. Put HEX_CORE_BEARER_TOKEN in the Secret, not the ConfigMap. The prefixed Compose variables do not configure Kubernetes deployments.

Both deployments set BRIGHTWAY_WORKSPACE_DIR=/var/lib/see-impacts/brightway. This is writable temporary working storage, not record persistence. Kubernetes mounts an emptyDir; Compose uses the container’s writable layer. Allow enough temporary disk space for the configured concurrency. No persistent volume is required by the supplied extension.

Keep .env files and token material out of version control. If requests pass through a reverse proxy, configure its response timeout to accommodate calculations up to the configured worker time limit.

Images

The supplied image references select these published releases:

Compose defines these defaults in .env.example; Kubernetes deployment manifests use the same versions. The JSONDB image belongs only to the optional Compose adapter slot, not the baseline or Kubernetes deployment.

Existing compose/.env files are not updated automatically. Set their image variables to the selected release tags when adopting this template version. Image overrides remain supported; use explicit release tags or digests rather than floating latest references, and keep Compose and Kubernetes references aligned.