Skip to main content

Configuration options

tip

Medatarun starts with sensible defaults and requires no configuration for a basic setup. This page documents the available options if you need to go further.

Directories​

When you launch Medatarun, it looks for two environment variables

  • MEDATARUN_HOME is the technical runtime directory used by Medatarun. It contains configuration files, logs, secrets and runtime-generated data.
  • MEDATARUN_APPLICATION_DATA is the directory where Medatarun stores your data and projects.

It can be the same directory or not. Your choice. In most cases, you don’t need to set these variables. Defaults work out of the box.

If you don't define them (the default options) they will be where you unzipped Medatarun.

Server​

You can configure server host and port. This acts when the server start, and also tell the CLI what server to connect to.

KeyTypeDefault valueDescription
Server
medatarun.public.base.urlString<generated>Public base URL of the Medatarun instance.
This is the externally visible URL used for generated links and redirects.
Override it when Medatarun is deployed behind a reverse proxy or accessed via a different hostname.
If not set, it is derived from the server host and port (http://<host>:<port>).
medatarun.server.hostString0.0.0.0Hostname or IP address the server binds to.
medatarun.server.portInteger8080TCP port the server listens on.
Database
medatarun.storage.datasource.jdbc.dbengineStringsqliteDatabase engine used by the storage layer. Supported values are sqlite and postgresql.
medatarun.storage.datasource.jdbc.urlString<generated for sqlite>JDBC URL used to connect to the storage database. If omitted with sqlite, Medatarun uses a database file under MEDATARUN_HOME/data/database.db.
medatarun.storage.datasource.jdbc.properties.*StringAdditional JDBC property. Replace * with the JDBC property key to pass through to the JDBC driver (for example user or password).
Auth
medatarun.auth.bootstrap.secretString<generated>Bootstrap secret used to obtain the initial administrator access.
In most environments, this value does not need to be set.
If not provided, Medatarun generates a random secret at startup and prints it in the logs.

In environments where startup logs are not accessible (for example when running in containers or managed platforms), you should explicitly set this value. Minimum length is 20 characters.
medatarun.auth.jwt.default.issuerStringDefault issuer used for JWTs generated by Medatarun. If not configured, Medatarun uses urn:medatarun:internal.
medatarun.auth.jwt.default.audienceStringmedatarunDefault audience used for JWTs generated by Medatarun.
medatarun.auth.jwt.default.ttl.secondsInteger3600Default lifetime in seconds for JWTs generated by Medatarun.
medatarun.auth.jwt.trusted.issuersCSVComma separated list of accepted JWT issuers. Each name will be used to get further configuration.
medatarun.auth.jwt.trusted.issuer.xxx.issuerStringRequired for every issuer. In the property name, replace xxx with one your issuer names defined in medatarun.auth.jwt.trusted.issuers. The value must be the exact name of iss claim as it appears in the JWT.
medatarun.auth.jwt.trusted.issuer.xxx.jwksURLRequired for every issuer. Absolute URL of your issuer's JWKS. You can often get it from its .well-known/openid-configuration (jwks_uri in this document's JSON). Otherwise ask your provider. It is the URL where we'll download the public keys of your issuer to validate their tokens.
medatarun.auth.jwt.trusted.issuer.xxx.algorithmsCSVComma separated list of algorithms that this issuer will sign its JWT with. We only support RS256 and ES256. If you let this empty (or don't provide it), it is assumed RS256 only.
medatarun.auth.jwt.trusted.issuer.xxx.audiencesCSVComma separated list of audiences that we need to check. If you let this empty (or not defined), no audience checks will be done. If you set some audiences, it is required that your JWT contains an aud with at least one of the audiences in this configuration.
medatarun.auth.jwt.jwks.cache.durationseconds600Duration (in seconds) we keep public keys in our local cache. Each JWT needs to be validated against your issuer public key. This is the time we keep the keys until we ask for a fresh one.
medatarun.auth.oauth.client.registration.retention.daysInteger7Retention duration in days for clients registered through the OAuth Dynamic Client Registration Protocol. If no activity is observed for a client after this period, it is automatically removed. Defaults to 30 days
medatarun.auth.oauth.refresh.token.ttl.secondsInteger2592000Lifetime in seconds for OAuth refresh tokens generated by Medatarun.
medatarun.auth.ui.oidc.authorityURLIf you let this empty, it is assumed Medatarun's UI will use our built-in OIDC provider. Then this value will depend on your medatarun.public.base.url and you don't have to take care of it. If specified, our UI will call your IdP to sign your users (OpenId Connect). In this case you need to specify your OIDC provider's authority URL (from which we will auto-discover its OIDC configuration).
medatarun.auth.ui.oidc.clientidStringIf you have configured an OIDC authority and registered Medatarun as a client application, this is the name of the client id you used to register Medatarun in your OIDC Identity Provider.
Observability
medatarun.telemetry.enabledStringfalseEnables OpenTelemetry integration. Default is false. Once enabled, you can configure OpenTelemetry Java configuration to send spans to your observability stack. See https://opentelemetry.io/docs/languages/java/configuration/ and our documentation. Note that we use the zero-code SDK autoconfigure mode, so you can configure with environment variables or system properties.

Note: frontend OIDC configuration is independent of JWT validation configuration. The client-id is never used as a JWT audience.

CLI​

The CLI uses the same configuration properties to determine which Medatarun instance to connect to. The server host, port, and public base URL follow the same rules and defaults as the server configuration.

KeyTypeDefault valueDescription
CLI
medatarun.public.base.urlString<generated>Base URL of the Medatarun server to connect to. If not set, it is derived from the server host and port (http://<host>:<port>).
medatarun.server.hostString0.0.0.0Hostname or IP address of the Medatarun server to connect to. Ignored if medatarun.public.base.url is present.
medatarun.server.portInteger8080TCP port of the Medatarun server to connect to. Ignored if medatarun.public.base.url is present.
medatarun.auth.tokenString<none>Authentication token used by the CLI when connecting to a Medatarun instance.

The CLI authenticates to the Medatarun API using a pre-configured authentication token. To learn more about authentication tokens: Managing users

How to configure​

Medatarun reads configuration properties from multiple configuration sources in this order:

  • as Java properties on the command line: For example medatarun -Dmedatarun.server.port=8081 serve
  • as environment variables: Here, you must define them in uppercase, replacing the doc . with underscores _ (for example MEDATARUN_SERVER_PORT=8080)
  • in .env files in MEDATARUN_HOME
  • in config/medatarun.properties file in MEDATARUN_HOME folder (this file doesn't exist in your download, you have to create it).
note

These configuration patterns are the ones we test.

Medatarun relies on the Java MicroProfile Config specification, with Smallrye config as implementation choice. This is mentioned here so you know exactly what is underneath and where to look if you run into configuration-related issues.

As an open source project, we cannot test every possible setup or environment. If your configuration behaves unexpectedly, the SmallRye Config documentation is the right place to dig into the details.

Logging configuration​

When running in server mode (medatarun serve) the default strategy is to log info, warnings and errors in the standard console (stdio).

When running in CLI mode (medatarun command...) strategy is to write warnings and errors on error console (stderr), and infos in standard console (stdio).

If this is ok for you, you can stop here.

This can be changed to suit your integration needs.

Medatarun uses SLF4J and LogBack for logging.

In your MEDATARUN_HOME (install directory), file config/logback.xml will be read for Logback configuration.

Configuration file content is explained in LogBack documentation here.

Telemetry and observability​

Medatarun can emit telemetry with OpenTelemetry.

Telemetry is what Medatarun reports about itself while it is running: requests, timings, metrics, technical errors, and whatever is useful when you need to understand what happens in production.

Medatarun is made to be used by autonomous AI agents, so you need a way to see what they actually do when they interact with the application. That is where telemetry becomes important.

note

This is not usage tracking by the Medatarun project. Medatarun does not send telemetry to us or to any Medatarun-operated service. The telemetry is produced by your instance, and you decide where it is sent.

It is disabled by default because we know that not everybody has ready observability tools.

To enable telemetry:

medatarun.telemetry.enabled=true

If telemetry is enabled and that no collector or backend are configured, or not reachable, Medatarun continues to run normally, but you will see telemetry export errors in the logs because telemetry data cannot be delivered.

Medatarun uses the OpenTelemetry Java SDK. Export is configured using the standard OpenTelemetry Java SDK autoconfigure mode, with environment variables and JVM system properties.

For example:

OTEL_SERVICE_NAME=medatarun
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

See https://opentelemetry.io/docs/languages/java/configuration/ for the full configuration.

Then you can send telemetry to the tools you use: Prometheus, Grafana Tempo, Jaeger, Datadog, SigNoz, New Relic, or whatever can receive OpenTelemetry-compatible data.