Configuration
You can configure the image using environment variables.
-
LogLevel: the highest level of log messages that should appear in the output. Values:TRACEDEBUGINFOWARNERROR
The logs are directed to the standard output and can be queried using the command docker logs <container name>.
-
SslEnabled: whether the container itself should manage SSL. If your runtime environment manages SSL or you don't need an SSL connection (not recommended in production environments), set this tofalse. Values:falsetrue
Should you enabled SSL, set these environment variables as well:
-
SslKeystore: the SSL key store path inside the container. You can provide an outer key store as well, if you mount the folder, that contains the key store, as a volume to the container with the -v parameter of thedocker runcommand. E.g. if your key store namedkeystore.jksis in/path/to/configfolder on the host machine and you mount the folder with the -v parameter as/opt/config(see below), then you can setSslKeystoreenvironment variable to/opt/config/keystore.jks.docker run \
--env-file /path/to/.env \
-p 8080:8080 \
-v /path/to/config:/opt/config \
--name carmen-worker \
public.ecr.aws/arcloud/carmen-worker:x86-64 -
SslKeystorePassword: the password of the key store. -
SslKeyAlias: the alias to be used as the SSL certificate that identifies the key in the key store. -
SslKeyPassword: the password used to access the key in the key store.
-
CarmenWorkerNodeName: a human-readable name that uniquely identifies this container in your environment. This name will be included in API responses to help with debugging. -
CarmenWorkerInitDefaultEngines: whether the container should initialize the default recognition engines when starting up. Values:falsetrue
-
CarmenWorkerMaxFileSize: maximum allowed size, in bytes, of POST requests made to the/vehicleor/transportendpoint. -
CarmenWorkerVehicleRegions: you can restrict the regions loaded during initialization. The value passed should be a JSON array of strings, e.g.["eur"]. -
CarmenWorkerTransportTypes: you can restrict the code types loaded during initialization. The value passed should be a JSON array of strings, e.g.["iso"]. -
CarmenWorkerHandlerCount: the (integer) number of processing threads to start.- You need to have at least as many licenses as the number set here.
- This number determines how many engine instances are initialized.
- We recommend this parameter to be less than or equal to the number of CPU cores available.
-
CarmenWorkerInitDefaultEngines:true(default) if the default engines should be loaded at initialization time,falseotherwise.trueresults in a slower startup time but the initialized container can serve requests immediately.falsedelays initialization of each engine until the first request that requires running that engine. -
CarmenWorkerBacklog: an integer indicating how many requests other than the ones being processed at the moment will be queued. Requests above this number will be discarded. -
CarmenWorkerRequestTimeout: the (integer) number of seconds after which to return a timeout response if processing takes too long. -
ApiKey: [YOUR_API_KEY]Please use your real Carmen® Cloud API key instead of the
[YOUR_API_KEY]placeholder.- The container needs to connect to our cloud-based License Service to acquire license locks.
Result storage and notifications for all APIs
Worker builds supporting common result notifications can publish Vehicle, Transportation & Cargo and PR results through an external AMQP 0-9-1 broker. This is optional. Configure an existing private S3-compatible bucket and broker, including the exchange, queue and bindings. A consumer can forward notifications to your HTTP webhook; the Worker does not install a broker or webhook server. For example:
RESULT_S3_BUCKET=carmen-results
RESULT_S3_ENDPOINT=https://minio.internal:9000
RESULT_S3_REGION=us-east-1
RESULT_S3_PATH_STYLE=true
RESULT_S3_ACCESS_KEY_FILE=/run/secrets/result-storage-access-key
RESULT_S3_SECRET_KEY_FILE=/run/secrets/result-storage-secret-key
RESULT_S3_SERVER_SIDE_ENCRYPTION=false
RESULT_MQ_URL=amqps://user:password@broker.example.com/vhost
RESULT_MQ_EXCHANGE=recognition-results
RESULT_MQ_ROUTING_KEY=recognition.result
Mount credential files read-only. Instead of the file settings, you can supply RESULT_S3_ACCESS_KEY and RESULT_S3_SECRET_KEY directly; supply both credentials and do not combine a value with its file setting. With MinIO, these are storage credentials and no AWS account is required. Without explicit credentials, the AWS default credential chain is used. Trust the storage and broker TLS certificates; protect the broker URL because it contains credentials. Use RESULT_S3_SERVER_SIDE_ENCRYPTION=true when storage supports AES256 encryption, and always provide encryption at rest. AWS storage requires encryption.
Each successful Vehicle or Transport request stores its final JSON result and original input images under its API-specific prefix. A notification follows a successful write and contains api, bucket, prefix, objectKeys, requestId, eventId and lifecycle metadata, rather than recognition data or signed URLs. The recipient retrieves objects using its own access to the same storage. It must deduplicate by event ID and tolerate out-of-order delivery. PR retains its transaction artifacts and can send intermediate and final events; inspect isFinal.
Storage and notification work runs in a bounded background queue. Failure or a full queue produces a rate-limited warning and does not fail the successful recognition response. Delivery makes one attempt, without persistent buffering, retry or delivery guarantee. Configure storage retention and least-privilege object access for the Vehicle and Transport prefixes; failed writes can leave partial objects without a notification. PR storage also needs the transaction permissions described below.
PR-specific storage requirements
The following settings apply to Worker builds that include PR document recognition and result notifications. Check your image's release notes for availability. PR is disabled by default and requires an image containing the PR native modules and data.
PR uses the common storage and notification settings above. Its document transactions additionally require the following engine and download settings; adjust the engine and endpoint for your deployment:
CarmenWorkerEnabledApis='["pr"]'
CarmenWorkerPrRegions='["world"]'
PrEngines='{"":"procr-world"}'
PR_S3_PUBLIC_DOWNLOAD_ENDPOINT=https://storage.example.com
PR_TRANSACTION_TTL_SECONDS=3600
PR can use a separate bucket with PR_TRANSACTION_BUCKET, separate storage credentials and endpoints with PR_S3_*, and a separate broker destination with PR_RESULT_MQ_*. These overrides follow the credential and TLS rules above; the PR-specific default routing key is pr.result. If no PR override is set, the common settings apply. Standalone PR requires a private S3-compatible bucket and does not fall back to local storage.
The worker must trust the storage endpoint's TLS certificate. PR_S3_PUBLIC_DOWNLOAD_ENDPOINT is the HTTPS origin clients use for signed artifact downloads; its certificate must be trusted by both clients and the worker. Keep the bucket private and treat signed links as bearer credentials. Grant the storage account the required GetObject, PutObject and DeleteObject permissions under pr22/*. Batch-capable builds also require ListBucket limited to pr22/_batch/ for background session maintenance. The store must support SigV4, ETags, conditional PUT with If-Match and If-None-Match, and conditional DELETE with If-Match; verify these against your deployment.
Configure lifecycle expiry for the private pr22/ prefix, for example after one day. Transactions expire logically after PR_TRANSACTION_TTL_SECONDS (default 3600 seconds, range 60–86400); physical lifecycle deletion is asynchronous. Artifact uploads request AES256 server-side encryption by default. If your MinIO deployment does not support it, set PR_S3_SERVER_SIDE_ENCRYPTION=false and provide encryption at rest through the storage deployment. For browser downloads, configure the bucket's CORS policy for the client origins and download requests.