kastoria-studyprocessor
A DICOM study processor that follows the DICOMStudy Changelog and projects
each committed study into the query surfaces (DICOMProcessed) and FHIR. It is
a one-shot image with no listening port: one invocation is one Execution,
which becomes a Run by taking the Run Lease, then exits. A deployment starts it
on a schedule.
Runtime details
| Property | Value |
|---|---|
| Runtime base image | kastoria-core (final stage), itself node:24-alpine |
| Exposed port | none (CLI, runs to completion) |
| Container user | node (non-root) |
| Entrypoint | node --import ./dicom-study-processor/src/instrumentation.js ./dicom-study-processor/bin/cli.js |
| Health check | none (not a long-running service) |
| Stop signal | SIGTERM (a signaled Run records its outcome and exits 0) |
Exit codes:
0 when the Lease was taken and released whatever the Run did, and
also 0 when another Execution holds the Lease (the no-op tick).
Non-zero exits occur when:
- A failure happened before the Lease was reached — configuration or storage initialization.
- A bad input argument is provided.
- A second
SIGTERMis received. - Reading the Lease failed.
- An exception is thrown during the close.
node_modules for npm/npx are stripped from the runtime image.
OCI labels
| Label | Value |
|---|---|
org.opencontainers.image.title |
DICOM Study Processor |
org.opencontainers.image.description |
Study processing pipeline for Kastoria Health |
org.opencontainers.image.licenses |
Proprietary |
org.opencontainers.image.url |
https://github.com/merkalis-io/kastoria-health |
org.opencontainers.image.documentation |
https://github.com/merkalis-io/kastoria-health |
io.kastoria.health-endpoint |
(empty — no health endpoint) |
The org.opencontainers.image.version, org.opencontainers.image.revision,
org.opencontainers.image.created, org.opencontainers.image.source,
io.kastoria.base-image, and io.kastoria.service labels are injected at
build time by the CI/CD pipeline.
Pull and verify
Promoted images are published to the Distribution Registry under the customer namespace:
docker pull acrmerkalisdist0c66.azurecr.io/<customer>/kastoria-studyprocessor:<release-tag>
notation verify acrmerkalisdist0c66.azurecr.io/<customer>/kastoria-studyprocessor:<release-tag>
See the Distribution Registry guide for authentication and trust setup.
Environment variables
| Variable | Secret | Required | Default | Description |
|---|---|---|---|---|
NODE_ENV |
No | No | production |
Environment; startup fails if unset. |
KASTORIA_CONFIG_JSON[1] |
Yes | one of these | — | Storage configuration as an inline JSON string. |
KASTORIA_CONFIG_FILE[1] |
No | one of these | — | Path to a storage configuration JSON file. |
STUDY_PROCESSOR_INSTANCE_CONCURRENCY |
No | No | 20 |
How many SOP instances of one study are in flight at once. |
STUDY_PROCESSOR_STUDY_CONCURRENCY |
No | No | 4 |
How many studies a Run projects at once; multiplies against the instance concurrency. |
STUDY_PROCESSOR_VISIBILITY_DELAY_MS |
No | No | 5000 |
How far short of NOW a Changelog read stops. |
STUDY_PROCESSOR_BATCH_SIZE |
No | No | 100 |
Entries one bounded Changelog read asks for. |
STUDY_PROCESSOR_RUN_BUDGET_MS |
No | No | 600000 |
Run Budget: how long, from process start, a Run may take new work. Floor 60000; a lower value throws at startup. |
SHUTDOWN_HARD_TIMEOUT_MS |
No | No | 10000 |
Hard deadline in ms for the tear-down after a Run ends. |
OTEL_ENABLED[2] |
No | No | false |
Set to true to enable OpenTelemetry export. |
OTEL_EXPORTER_OTLP_ENDPOINT[2] |
No | No | — | OTLP collector endpoint, e.g. http://otel-gateway:4317. |
OTEL_DEBUG[2] |
No | No | — | Set to true for verbose OTel diagnostic logging. |
The CLI subcommand (process DICOMStudy) is passed at run time.
Deploying to an Azure Container Apps Environment
[1] At least one of KASTORIA_CONFIG_JSON / KASTORIA_CONFIG_FILE is required for storage initialization. If both are set the value of KASTORIA_CONFIG_JSON is used. See Configuration for the document's contents.
[2] If OTEL_ENABLED is not explicitly set to true, OpenTelemetry metric/trace/logging is disabled.
Job configuration
The image is meant to run as a batch job that is setup to be run on a regular schedele. There is no long-running process to keep alive; the deployment is responsible for starting execution on a cadence. The following launch arguments should be passed into the container
["process", "DICOMStudy"]
To details on setting up the execution cadence and launch arguments in a deployed environment, see the
jobs configuration documentation for the appropriate Terrform/OpenTofu compute module.
Available versions
v0.10.0v0.9.1— deprecated for security reasons (CVE-2026-101916); usev0.10.0