Skip to content

Configuration

The Dory Processor SDK is configured through a small typed schema (DoryConfig), a set of presets, and a handful of environment variables. Most processors need to set little or nothing. The defaults are production-ready, and on the Dory platform the orchestrator supplies the runtime settings for you, including a description of the sensor your processor is bound to.

DoryConfig schema

DoryConfig is a Pydantic model with ten fields. Any extra keys are ignored.

Field Type / range Default Purpose
startup_timeout_sec int, 1–300 30 Max time for startup, including state restore.
shutdown_timeout_sec int, 1–300 30 Max time for graceful shutdown, including state flush.
health_port int, 0–65535 8080 Health/metrics server port; 0 = auto-select a free port.
state_backend configmap / pvc / s3 / local configmap Where state is persisted. See State Management.
log_level DEBUG / INFO / WARNING / ERROR / CRITICAL INFO Log verbosity.
memory_watchdog_enabled bool true Trigger a graceful restart when memory nears its limit.
memory_watchdog_threshold float, 0.5–0.99 0.90 Fraction of the memory limit that counts as pressure.
memory_watchdog_interval_sec int, 1–300 10 Seconds between memory samples.
memory_watchdog_limit_bytes int, ≥ 0 0 Explicit memory limit in bytes; 0 = detect the container's limit.
restart_stable_reset_sec int, 1–86400 300 Uptime after which a restart no longer counts toward a crash loop.

You can set these in a YAML config file, via DORY_* environment variables, or by passing a log_level / config_file to DoryApp(...).

Note

Event delivery is handled by the Dory platform. The broker connection and the credential your processor publishes with are supplied at runtime. They are not part of DoryConfig, and you should not set them for the platform. See Set by the platform.

Presets

A preset is a named starting point for the first five fields above. The others keep their defaults. When running locally, select one with the DORY_PRESET environment variable or a preset key in your config file.

Preset log_level health_port state_backend startup_timeout_sec shutdown_timeout_sec
development DEBUG 0 (auto) local 30 30
production INFO 8080 configmap 120 30
high-availability INFO 8080 pvc 120 60

When running locally without a preset, the SDK uses development. In Kubernetes it always starts from production, and DORY_PRESET is not read.

Config file

If you prefer a file, drop a dory.yaml next to your processor (or point DORY_CONFIG_FILE at one). It is consulted only when running locally. When orchestrated on the platform, the file is not read.

preset: production
log_level: INFO
health_port: 8080
state_backend: configmap

The SDK looks for a config file in this order (first hit wins): an explicit path you pass to DoryApp, then DORY_CONFIG_FILE, then /etc/dory/config.yaml, /app/config/dory.yaml, and finally ./dory.yaml.

How settings combine

When running locally, settings merge with this precedence (highest wins):

env vars  >  config file  >  preset  >  defaults

When running orchestrated on Dory, the orchestrator is the source of truth. YAML files and presets are ignored: the SDK starts from the production preset and applies the environment variables the platform sets. You don't have to do anything for this to work.

Environment variables you set

These are the variables a processor developer sets directly. The variables in Set by the platform are supplied for you.

Configuration

Variable Default Effect
DORY_PRESET — Select a preset (local runs only; see above).
DORY_CONFIG_FILE — Path to a YAML config file (local runs only).
DORY_STARTUP_TIMEOUT_SEC 30 Startup timeout (startup_timeout_sec).
DORY_SHUTDOWN_TIMEOUT_SEC 30 Shutdown timeout (shutdown_timeout_sec).
DORY_HEALTH_PORT 8080 Health/metrics server port (0 = auto).
DORY_STATE_BACKEND configmap State backend (configmap / pvc / s3 / local).
DORY_LOG_LEVEL INFO Log level.
DORY_MEMORY_WATCHDOG_ENABLED true Memory watchdog on or off (true / false).
DORY_MEMORY_WATCHDOG_THRESHOLD 0.90 Memory pressure threshold.
DORY_MEMORY_WATCHDOG_INTERVAL_SEC 10 Seconds between memory samples.
DORY_MEMORY_WATCHDOG_LIMIT_BYTES 0 Explicit memory limit (0 = detect).
DORY_RESTART_STABLE_RESET_SEC 300 Uptime that resets the crash-loop count.

Warning

Only the ten variables from DORY_STARTUP_TIMEOUT_SEC down map onto the DoryConfig schema. Other DORY_* variables either configure a subsystem directly (such as the S3 backend below) or are set by the platform.

S3 state backend

Only relevant if you choose state_backend = s3. The bucket and region are the settings you'd typically pick; AWS credentials come from the runtime environment (the standard AWS variables or an IAM role).

Variable Default Effect
DORY_S3_BUCKET — (required for S3) S3 bucket for state.
DORY_S3_PREFIX dory-state Key prefix.
DORY_S3_REGION / AWS_REGION — Bucket region.
DORY_S3_ENDPOINT_URL — Custom S3-compatible endpoint.

See State Management for backend trade-offs.

Local tracing

Tracing is automatic on the platform, so you don't configure it. The one variable worth knowing locally:

Variable Default Effect
OTEL_EXPORTER_OTLP_ENDPOINT — OTLP endpoint to export spans to. When unset, spans print to the console, which is handy when developing locally.

See Observability → Traces.

Set by the platform

When the platform starts your processor, it sets the variables below. Don't set them yourself for a platform run. Locally you can set them to imitate one.

The sensor your processor is bound to

A processor runs one template against one sensor, and the platform describes that sensor in the environment:

Variable What it holds
PROCESSOR_ID This processor's identity, and the first segment of every routing key it publishes. The SDK checks DORY_PROCESSOR_ID first, then PROCESSOR_ID.
DORY_SENSOR_ID The sensor this processor is bound to.
DORY_SENSOR_TYPE The sensor's type, such as camera or lidar.
DORY_SENSOR_CONNECTION_CONFIG How to reach the sensor, as JSON. It never contains a login: when a camera needs one, the platform signs in to it for you. See Reaching a camera.
DORY_SENSOR_METADATA The sensor's metadata, as JSON.
DORY_GEO_REFERENCE_POINTS The calibration points from the sensor's metadata, as a JSON array. Set only when the sensor has any.
DORY_GEOHASH The sensor's own location as a nine-character geohash. Set only when the sensor has a location.
DORY_APP_VERSION The version of your template this processor is running. The SDK reports it as the service version in traces.

DORY_SENSOR_TYPE, DORY_SENSOR_CONNECTION_CONFIG and DORY_SENSOR_METADATA are left unset when the sensor record has no value for them.

Every DORY_* variable is left out of ctx.config(), so read these with ctx.get_env("DORY_SENSOR_CONNECTION_CONFIG") and parse the JSON yourself.

Two of these don't do anything unless your code uses them:

  • DORY_GEOHASH is informational. publish() never reads it. The location in an event's routing key is always the GeoPoint your code passes. See Where the location comes from.
  • DORY_GEO_REFERENCE_POINTS is for your template. The SDK doesn't read it by itself. The SDK's reference camera example passes these points to CameraGeolocalizer to estimate a position per detection, which needs at least four points with its default method.

Note

The sensor may not belong to your organization. A subscription matches sensors for the subscriber, so your processor can be bound to another organization's public sensor. The connection config holds no login, but it still describes how to reach that organization's device. Never log DORY_SENSOR_CONNECTION_CONFIG or copy it into an event. See How a subscription reaches your template.

The platform also sets pod identity, tracing and state-access variables that the SDK uses internally. Your code doesn't need to read them.

Reaching a camera

For a camera, the stream_url in DORY_SENSOR_CONNECTION_CONFIG points at the platform, not at the camera itself. The platform signs in to the camera on your processor's behalf and passes the stream on, so open stream_url as it is and never add a username or password to it. The device login stays with the platform: nothing your processor receives contains it, whatever the sensor type.

The event broker

Your processor never configures the broker. On the platform, the broker settings come from a settings map shared by every processor, and the credential comes from a platform-managed secret, also shared. The SDK reads these variables:

Variable Default when unset What it holds
DORY_RABBITMQ_OAUTH2_TOKEN_URL — Where the SDK obtains broker access tokens. The SDK creates a publisher only when this is set.
DORY_RABBITMQ_OAUTH2_CLIENT_ID — The publishing credential's client id.
DORY_RABBITMQ_OAUTH2_CLIENT_SECRET — The publishing credential's secret.
DORY_RABBITMQ_HOST — The broker host. The SDK connects on port 5671.
DORY_RABBITMQ_EXCHANGE dory.output The exchange events are published to. The platform sets its event exchange here.
DORY_RABBITMQ_VHOST / The broker virtual host.
DORY_RABBITMQ_TLS_ENABLED true Whether the connection uses TLS.

The credential is write-only. Every processor publishes with the same platform-managed credential, which can only publish: it cannot declare queues, bind or read, so a processor never consumes other processors' events. The SDK obtains short-lived access tokens from it for you. The client secret's name contains SECRET, so it is excluded from ctx.config() in any case.

Running locally. Without DORY_RABBITMQ_OAUTH2_TOKEN_URL there is no publisher, and publish() raises a RuntimeError. That is the expected local state: the template scaffold checks for a publisher and logs no publisher configured; would emit … instead. To try publishing against a broker of your own, set the variables above. The scaffold's .env.example lists the main ones, commented out. Set DORY_RABBITMQ_EXCHANGE explicitly, because its default is not the platform's exchange. See Output & Events.

Application configuration

Your own app settings (for example CAMERA_FEED_URL or MODEL_PATH) are read from the environment and surfaced through ctx.config(). Two groups are deliberately left out of config():

  • Every DORY_* and KUBERNETES_* variable, including the platform-set variables above.
  • Credential-looking names: anything containing SECRET, TOKEN, PASSWORD, PASSWD, PRIVATE_KEY, ACCESS_KEY, CREDENTIAL, DATABASE_URL, DB_URL, CONNECTION_STRING or AWS_.

Read any of those explicitly with ctx.get_env("MY_VAR") when you need them. The filter matches only those markers, so a name such as API_KEY still appears in config(). Give credentials a name that matches a marker, or don't rely on the filter to hide them. See Core Concepts.