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.
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):
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. |
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_GEOHASHis informational.publish()never reads it. The location in an event's routing key is always theGeoPointyour code passes. See Where the location comes from.DORY_GEO_REFERENCE_POINTSis for your template. The SDK doesn't read it by itself. The SDK's reference camera example passes these points toCameraGeolocalizerto 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_*andKUBERNETES_*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_STRINGorAWS_.
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.