Docs/Platform/Configuration

Configuration

Configure runtime endpoints, security, persistence, validation, retention, backup, and operational behavior. The distributed application.properties includes detailed inline comments for every setting.

Configuration file

FireSonic runtime configuration is stored in ./config/application.properties.

config/
├─ application.properties
├─ license.lic
└─ certs/

Essential configuration

Review these values for every installation before processing production traffic.

Property	Default / Example	Purpose
`license.file`	`./config/license.lic`	License file location.
`payload.crypto.keys.k1.password`	empty	Encryption secret used to protect persisted HL7 payloads. Set a strong unique secret and back it up securely.
`mllp.port`	`2575`	Incoming HL7 v2 MLLP port.
`fhir.server.base.url`	environment/default	Target FHIR server endpoint.
`fhir.server.auth.type`	`none`	FHIR authentication mode: `none`, `basic`, or `bearer`.
`management.auth.username`	`admin`	Administration Console username.
`management.auth.password`	`change-me`	Change immediately for production deployments.

Environment variables and secrets

Use environment-variable placeholders or your deployment environment’s secret-management system for passwords, tokens, encryption keys, and external-service credentials. Never commit production secrets to source control.

fhir.server.base.url=${FHIR_SERVER_URL:http://localhost:8080/fhir}
fhir.server.auth.basic.password=${FHIR_PASSWORD}
fhir.server.auth.bearer.token=${FHIR_BEARER_TOKEN}
payload.crypto.keys.k1.password=${FS_PAYLOAD_KEY}
management.auth.password=${FS_ADMIN_PASSWORD}

Additional trusted TLS certificates

FireSonic uses the JVM default trusted Certificate Authorities. When additional certificate loading is enabled, FireSonic also trusts valid X.509 certificates found in ./config/certs. This is useful when a FHIR or terminology server uses a hospital/private CA.

tls.certs.enabled=true
tls.certs.dir=./config/certs

Supported certificate file extensions: .pem, .crt, and .cer.
Certificates are loaded once during FireSonic startup.
Restart FireSonic after adding, replacing, or removing certificates.

config/
├─ application.properties
├─ license.lic
└─ certs/
   ├─ hospital-root-ca.crt
   └─ internal-fhir-ca.pem

Property reference

The groups below mirror the sections in the distributed application.properties file.

Licensing

Property	Default	Description
`license.file`	`./config/license.lic`	Path to the FireSonic license file.

Database & Persistence

Property	Default	Description
`db.path`	`./data/fs.db`	SQLite database used for message persistence, retry tracking, auditing, and restart recovery.
`payload.compression.enabled`	`true`	Compress HL7 payloads before encryption and persistence to reduce database and backup size.
`payload.crypto.activeKey`	commented	Optional active encryption key identifier when multiple encryption keys are configured.
`payload.crypto.keys.k1.password`	empty	Password used to derive encryption key `k1`. Use a unique strong secret.

Storage guidance

Keep the SQLite database on local disk attached to the same system where FireSonic runs. Do not place db.path on mounted network storage, shared drives, or remote filesystems.

Critical

Losing payload.crypto.keys.k1.password makes encrypted persisted payloads unrecoverable. Store the secret securely and include it in your disaster-recovery plan.

Semantic Validation Rules

Property	Default	Description
`semantic.rules.enabled`	`true`	Enable semantic validation after conversion and before FHIR delivery.
`semantic.rules.dir`	`./rules/semantic`	Directory containing Groovy DSL semantic rules.
`semantic.rules.autoreload` Commercial	`true`	Automatically validate and activate changed semantic-rule generations without restarting the FireSonic runtime.

Groovy Scripts

Property	Default	Description
`scripts.dir`	`./scripts`	Directory containing customer Groovy integration scripts.
`scripts.autoreload` Commercial	`false`	Compile, validate, and activate changed script generations without restarting the FireSonic runtime.
`scripts.autoreload.scanIntervalMs` Commercial	`2000`	How often the script directory is scanned for changes.
`scripts.autoreload.quietPeriodMs` Commercial	`1000`	How long changed files must remain stable before reload is attempted.
`runtime.script.timeout.enabled`	`true`	Enable per-hook execution timeout enforcement.
`runtime.script.timeout.ms`	`60000`	Maximum hook execution time in milliseconds.

MLLP Listener

Property	Default	Description
`mllp.port`	`2575`	TCP port for incoming HL7 v2 MLLP connections.
`mllp.charset`	`UTF-8`	Character set used to decode incoming HL7 messages.
`mllp.socket.timeout.ms`	`30000`	Socket read timeout in milliseconds.
`mllp.max.message.bytes`	`5000000`	Maximum accepted HL7 message size in bytes.
`mllp.backlog`	`30`	Maximum number of pending TCP connections.

TLS Certificates

Property	Default	Description
`tls.certs.enabled`	`true`	Load additional trusted X.509 certificates in addition to JVM default trusted CAs.
`tls.certs.dir`	`./config/certs`	Directory containing additional `.pem`, `.crt`, and `.cer` certificates. Certificates are loaded once during FireSonic startup.

FHIR Server & Delivery

Property	Default	Description
`fhir.server.base.url`	`${FHIR_SERVER_URL:http://host.docker.internal:8080/fhir}`	Primary FHIR server endpoint.
`fhir.server.timeout.ms`	`30000`	FHIR request timeout in milliseconds.
`fhir.server.auth.type`	`none`	Authentication mode: none, basic, or bearer.
`fhir.server.auth.basic.username`	empty	Basic-auth username.
`fhir.server.auth.basic.password`	empty	Basic-auth password.
`fhir.server.auth.bearer.token`	empty	Bearer token.
`fhir.delivery.max.bundles.per.second`	`0`	Maximum outbound FHIR bundles per second. `0` means unlimited, subject to license limits.

FHIR Delivery Circuit Breaker Commercial

Property	Default	Description
`fhir.delivery.breaker.enabled` Commercial	`true`	Pause outbound FHIR delivery when repeated delivery failures are detected.
`fhir.delivery.breaker.failure.threshold` Commercial	`3`	Consecutive delivery failures required to open the breaker.
`fhir.delivery.breaker.recovery.success.threshold` Commercial	`2`	Successful deliveries required in HALF_OPEN state to close the breaker and resume normal delivery.
`fhir.delivery.breaker.cooldown.ms` Commercial	`30000`	Pause duration before the breaker enters HALF_OPEN and tests downstream delivery again.

Terminology Server

Property	Default	Description
`terminology.server.base.url`	empty	Optional terminology endpoint. When blank, the main FHIR server is used.
`terminology.server.timeout.ms`	empty	Optional terminology request timeout.
`terminology.server.auth.type`	empty	Authentication mode: none, basic, or bearer.
`terminology.server.auth.basic.username`	empty	Basic-auth username.
`terminology.server.auth.basic.password`	empty	Basic-auth password.
`terminology.server.auth.bearer.token`	empty	Bearer token.

FHIR Extension Canonical Base URL

Property	Default	Description
`fhir.extension.base.url`	`https://firesonic.io/fhir`	Canonical base URL for custom FHIR extensions. Customer deployments should use the namespace owned by the organization that governs the extensions.

Web Administration Console

Property	Default	Description
`management.auth.enabled`	`true`	Enable HTTP Basic Authentication for the Administration Console.
`management.auth.username`	`admin`	Administration Console username.
`management.auth.password`	`change-me`	Administration Console password; change immediately in production.
`management.metrics.auth.enabled` Commercial	`false`	Enable authentication for the commercial metrics endpoint.
`management.host`	`0.0.0.0`	Management HTTP bind address.
`management.port`	`8181`	Administration and management HTTP port.
`admin.api.retry.batch.max.limit` Commercial	`5000`	Safety cap for one batch-retry request.

Queues & Workers

Property	Default	Description
`queue.received.capacity`	`10000`	Capacity of the received-message queue.
`queue.processing.capacity`	`10000`	Capacity of the processing queue.
`intake.threads` Commercial	`auto`	Configure intake concurrency for the deployment to increase throughput and better utilize available CPU resources.
`processor.threads` Commercial	`auto`	Configure processing concurrency for the deployment to increase throughput and better utilize available CPU resources.

Retry & Lease Configuration

Property	Default	Description
`processor.max.retry.attempts`	`5`	Maximum processing attempts before a message is marked failed.
`processor.base.backoff.ms`	`1000`	Base retry delay in milliseconds.
`processor.lease.ms`	automatic	Processing lease duration; normally calculated automatically.

Processing Circuit Breaker Commercial

Property	Default	Description
`processing.breaker.enabled` Commercial	`true`	Pause new processing when repeated identical processing failures are detected.
`processing.breaker.failure.threshold` Commercial	`5`	Repeated identical processing failures required to open the breaker.
`processing.breaker.window.ms` Commercial	`60000`	Time window for counting repeated identical processing failures.
`processing.breaker.cooldown.ms` Commercial	`300000`	Pause duration before processing resumes automatically.

Maintenance & Recovery

Property	Default	Description
`reloader.interval.seconds`	`30`	Background maintenance interval for recovery, queue reload, and retention housekeeping.
`reloader.empty.queue.threshold.ms`	`2000`	Internal tuning parameter; normally keep the default.

Message Retention

Property	Default	Description
`retention.filtered.days`	`3`	Retention for FILTERED messages.
`retention.processed.days`	`7`	Retention for PROCESSED messages.
`retention.failed.days`	`30`	Retention for REJECTED, DELIVERY_FAILED, and PROCESSING_FAILED messages.
`retention.purge.interval.minutes`	`60`	Interval between retention cleanup runs.

Backup

Property	Default	Description
`backup.enabled`	`false`	Enable scheduled SQLite database backups.
`backup.interval.hours`	`24`	Backup interval in hours; minimum 1.
`backup.directory`	`./backup`	Local backup directory.
`backup.retention.count`	`7`	Number of local backup files to keep.
`backup.external.directory`	empty	Copy database backups to an external destination such as a mounted disk, NAS, NFS share, or SMB share.
`backup.compress`	`true`	GZIP-compress backup files.

Advanced tuning

Keep advanced tuning values at their defaults unless workload characteristics or support guidance require a change. Examples include MLLP backlog, script timeout, retry/backoff parameters, circuit-breaker thresholds, queue capacities, and maintenance timing.