# Advanced Configuration Reference

> Source: https://docs.synthesized.io/tdk/latest/user_guide/040_reference/configuration/advanced_configuration
> For the complete documentation index, see [llms.txt](https://docs.synthesized.io/llms.txt).

This page documents advanced configuration properties and environment variables that are not commonly used but provide fine-grained control over TDK behavior. These properties can be set as environment variables in docker-compose.yml or in application.properties files.

> **TIP**
> Most users will not need to modify these settings. The defaults are optimized for typical use cases. Only adjust these properties if you have specific performance or operational requirements.

## Scheduling & Background Tasks

These properties control internal scheduled tasks such as cleanup operations and health checks.

### Task Run Lifecycle

Controls the scheduled check for terminating task runs.

- `GOVERNOR_SCHEDULING_TASK_RUN_TERMINATING_CHECK_DELAY_MILLIS`
  
  Initial delay before the first terminating check runs (in milliseconds).
  
  **Default**: `10000` (10 seconds)
  
  **Example**: Set to `86400000` (24 hours) to effectively disable frequent checks in test environments:
  
  ```properties
  GOVERNOR_SCHEDULING_TASK_RUN_TERMINATING_CHECK_DELAY_MILLIS=86400000
  ```
- `GOVERNOR_SCHEDULING_TASK_RUN_TERMINATING_CHECK_INTERVAL_MILLIS`
  
  Interval between terminating checks (in milliseconds).
  
  **Default**: `30000` (30 seconds)
  
  **Example**: Increase interval to reduce system load:
  
  ```properties
  GOVERNOR_SCHEDULING_TASK_RUN_TERMINATING_CHECK_INTERVAL_MILLIS=60000
  ```

### Connection Cache Cleanup

Controls how often database connection caches are cleaned up.

- `GOVERNOR_SCHEDULING_CONNECTION_CACHE_CLEANUP_INTERVAL_MILLIS`
  
  Interval for cleaning up cached database connections (in milliseconds).
  
  **Default**: `180000` (3 minutes)
  
  **Example**:
  
  ```properties
  GOVERNOR_SCHEDULING_CONNECTION_CACHE_CLEANUP_INTERVAL_MILLIS=300000
  ```

### Spawned Database Cleanup

Controls cleanup of temporary databases created during workflow execution.

- `GOVERNOR_SCHEDULING_SPAWNED_DATABASE_CLEANUP_INTERVAL_MILLIS`
  
  Interval for removing expired spawned databases (in milliseconds).
  
  **Default**: `3600000` (1 hour)
  
  **Example**: Check more frequently in development:
  
  ```properties
  GOVERNOR_SCHEDULING_SPAWNED_DATABASE_CLEANUP_INTERVAL_MILLIS=1800000
  ```

## Workflow Execution

These properties control workflow execution behavior, thread pools, and connection management.

### Workflow Runner

- `WORKFLOW_RUNNER_THREADS`
  
  Number of threads available for workflow execution.
  
  **Default**: `30`
  
  **Example**: Increase for better parallelism on high-core machines:
  
  ```properties
  WORKFLOW_RUNNER_THREADS=50
  ```
- `WORKFLOW_RUNNER_TERMINATION_MS`
  
  Timeout for workflow runner termination (in milliseconds).
  
  **Default**: `5000` (5 seconds)
  
  **Example**:
  
  ```properties
  WORKFLOW_RUNNER_TERMINATION_MS=10000
  ```

### Workflow Data Source Connection Pools

Controls connection pooling behavior for workflow data sources.

- `WORKFLOW_DATASOURCE_SYSTEMPOOLSIZE`
  
  Size of the system connection pool.
  
  **Default**: `3`
  
  **Example**:
  
  ```properties
  WORKFLOW_DATASOURCE_SYSTEMPOOLSIZE=5
  ```
- `WORKFLOW_DATASOURCE_SYSTEMPOOLSCACHEEXPIREACCESSECONDS`
  
  Time (in seconds) after which cached connection pools expire if not accessed.
  
  **Default**: `180` (3 minutes)
  
  **Example**:
  
  ```properties
  WORKFLOW_DATASOURCE_SYSTEMPOOLSCACHEEXPIREACCESSECONDS=300
  ```
- `WORKFLOW_DATASOURCE_SYSTEMPOOLSCACHESIZE`
  
  Maximum number of connection pools to cache.
  
  **Default**: `1024`
  
  **Example**:
  
  ```properties
  WORKFLOW_DATASOURCE_SYSTEMPOOLSCACHESIZE=2048
  ```
- `WORKFLOW_DATASOURCE_DEFAULTMAXIMUMPOOLSIZE`
  
  Default maximum size for individual connection pools.
  
  **Default**: `20`
  
  **Example**: Increase for data sources with high concurrent access:
  
  ```properties
  WORKFLOW_DATASOURCE_DEFAULTMAXIMUMPOOLSIZE=30
  ```

### Workflow Log Files

Controls where and how workflow execution logs are stored.

- `WORKFLOW_LOGFILE_LOCATION`
  
  Directory where workflow run log files are stored.
  
  **Default**: `logs/runs`
  
  **Example**: Store logs in a custom directory:
  
  ```properties
  WORKFLOW_LOGFILE_LOCATION=/var/log/tdk/workflows
  ```
- `WORKFLOW_LOGFILE_FILEPREFIXNAME`
  
  Prefix for log file names.
  
  **Default**: `run`
  
  **Example**:
  
  ```properties
  WORKFLOW_LOGFILE_FILEPREFIXNAME=workflow
  ```
- `WORKFLOW_LOGFILE_FILEEXTENSIONNAME`
  
  File extension for log files.
  
  **Default**: `log`
  
  **Example**:
  
  ```properties
  WORKFLOW_LOGFILE_FILEEXTENSIONNAME=txt
  ```

## Worker Configuration

Advanced settings for Synthesized Workers.

> **NOTE**
> For backward compatibility, `AGENT_*` environment variables are still supported and automatically remapped to `WORKER_*` at startup. If both are set, `WORKER_*` takes precedence.

### Worker Communication

- `WORKER_GRPC_PORT`
  
  gRPC port for worker communication.
  
  **Default**: `50055`
  
  **Example**:
  
  ```properties
  WORKER_GRPC_PORT=50060
  ```
- `WORKER_GRPC_MAXMESSAGESIZE`
  
  Maximum gRPC message size in bytes.
  
  **Default**: `52428800` (50 MB)
  
  **Example**: Increase for large workflow configurations:
  
  ```properties
  WORKER_GRPC_MAXMESSAGESIZE=104857600
  ```
- `WORKER_GRPC_COMPRESSION_ENABLED`
  
  Enable gRPC message compression.
  
  **Default**: `true`
  
  **Example**:
  
  ```properties
  WORKER_GRPC_COMPRESSION_ENABLED=false
  ```

### Worker Health

- `WORKER_ALIVEMINUTES`
  
  Number of minutes a worker is considered alive without heartbeat.
  
  **Default**: `2`
  
  **Example**: Increase tolerance for network issues:
  
  ```properties
  WORKER_ALIVEMINUTES=5
  ```
- `WORKER_CHECKTASKDELAY`
  
  Delay between worker task checks (in milliseconds).
  
  **Default**: Not set (uses Spring Boot defaults)
  
  **Example**:
  
  ```properties
  WORKER_CHECKTASKDELAY=1000
  ```

## Security & Authentication

Advanced security configuration options.

### JWT Configuration

- `JWT_ACCESS_TOKEN_EXPIRATION`
  
  Access token expiration time (in milliseconds).
  
  **Default**: `86400000` (1 day)
  
  **Example**: Reduce for higher security:
  
  ```properties
  JWT_ACCESS_TOKEN_EXPIRATION=3600000
  ```
- `JWT_REFRESH_TOKEN_EXPIRATION`
  
  Refresh token expiration time (in milliseconds).
  
  **Default**: `5184000000` (60 days)
  
  **Example**:
  
  ```properties
  JWT_REFRESH_TOKEN_EXPIRATION=2592000000
  ```
- `JWT_ISSUER`
  
  JWT token issuer identifier.
  
  **Default**: `io.synthesized`
  
  **Example**:
  
  ```properties
  JWT_ISSUER=mycompany.io
  ```

### Credentials Encryption

- `CREDENTIALS_ENCRYPTION_KEY`
  
  Base64-encoded key used for encrypting stored credentials.
  
  **Default**: Test key (must be changed in production)
  
  > **WARNING**
  > Always generate a new encryption key for production environments. If this key is lost, encrypted credentials cannot be recovered.
  
  **Example**:
  
  ```properties
  CREDENTIALS_ENCRYPTION_KEY=<base64-encoded-key>
  ```

### Governor Security Settings

- `GOVERNOR_SECURITY_SECRETEXPIRETIMESECONDS`
  
  Time (in seconds) before security secrets expire.
  
  **Default**: `30`
  
  **Example**:
  
  ```properties
  GOVERNOR_SECURITY_SECRETEXPIRETIMESECONDS=60
  ```
- `GOVERNOR_SECURITY_ALLOWEDCLOCKSKEWSECONDS`
  
  Allowed clock skew for time-based security checks (in seconds).
  
  **Default**: `0`
  
  **Example**: Allow up to 30 seconds of clock skew:
  
  ```properties
  GOVERNOR_SECURITY_ALLOWEDCLOCKSKEWSECONDS=30
  ```
- `GOVERNOR_SECURITY_DEFAULTROLE`
  
  Default role assigned to new users.
  
  **Default**: `USER`
  
  **Options**: `USER`, `ADMIN`
  
  **Example**:
  
  ```properties
  GOVERNOR_SECURITY_DEFAULTROLE=ADMIN
  ```
- `GOVERNOR_SECURITY_ALLOWEDORIGINPATTERNS`
  
  CORS allowed origin patterns (comma-separated).
  
  **Default**: `*` (all origins)
  
  **Example**: Restrict to specific domains:
  
  ```properties
  GOVERNOR_SECURITY_ALLOWEDORIGINPATTERNS=https://mycompany.com,https://*.mycompany.com
  ```
- `GOVERNOR_SECURITY_OWNERACCESSONLY`
  
  When `true`, users can only see and access their own workflows.
  
  **Default**: `false`
  
  **Example**: Enable for multi-tenant deployments:
  
  ```properties
  GOVERNOR_SECURITY_OWNERACCESSONLY=true
  ```

### SAML Configuration

- `GOVERNOR_SECURITY_SAML_AUTHORITIES_ENABLED`
  
  Enable automatic role assignment from SAML Identity Provider group memberships.
  
  **Default**: `false`
  
  **Example**:
  
  ```properties
  GOVERNOR_SECURITY_SAML_AUTHORITIES_ENABLED=true
  ```
- `GOVERNOR_SECURITY_SAML_AUTHORITIES_GROUP_ATTRIBUTE`
  
  The SAML assertion attribute containing the list of user group names.
  
  **Default**: `groups`
  
  **Example**:
  
  ```properties
  GOVERNOR_SECURITY_SAML_AUTHORITIES_GROUP_ATTRIBUTE=memberOf
  ```
- `GOVERNOR_SECURITY_SAML_AUTHORITIES_CONVERT_TO_UPPERCASE`
  
  Convert group names to uppercase before matching against role aliases.
  
  **Default**: `true`
  
  **Example**:
  
  ```properties
  GOVERNOR_SECURITY_SAML_AUTHORITIES_CONVERT_TO_UPPERCASE=false
  ```
- `GOVERNOR_SECURITY_SAML_AUTHORITIES_DEFAULT_ROLE`
  
  Default role assigned when no group matches any configured alias.
  
  **Default**: `MEMBER`
  
  **Options**: `MEMBER`, `ADMINISTRATOR`, `OWNER`
  
  **Example**:
  
  ```properties
  GOVERNOR_SECURITY_SAML_AUTHORITIES_DEFAULT_ROLE=MEMBER
  ```
- `GOVERNOR_SECURITY_SAML_SLO_ENABLED`
  
  Enable SAML Single Logout (SLO) to sign the user out of the Identity Provider when logging out of Governor.
  
  **Default**: `false`
  
  **Example**:
  
  ```properties
  GOVERNOR_SECURITY_SAML_SLO_ENABLED=true
  ```
- `GOVERNOR_SECURITY_SAML_DEFAULT_REGISTRATION_ID`
  
  The default SAML provider registration ID used for logout.
  
  **Default**: Not set
  
  **Example**:
  
  ```properties
  GOVERNOR_SECURITY_SAML_DEFAULT_REGISTRATION_ID=microsoft
  ```

See [Single Sign-On (SSO)](https://docs.synthesized.io/tdk/latest/user_guide/060_security_compliance/authentication/sso) for full SAML setup instructions including role alias configuration.

## Database Connection Management

Advanced database connection settings using HikariCP.

### HikariCP Connection Pool

- `SPRING_DATASOURCE_HIKARI_CONNECTIONTIMEOUT`
  
  Maximum time (in milliseconds) to wait for a connection from the pool.
  
  **Default**: `30000` (30 seconds)
  
  **Example**:
  
  ```properties
  SPRING_DATASOURCE_HIKARI_CONNECTIONTIMEOUT=20000
  ```
- `SPRING_DATASOURCE_HIKARI_IDLETIMEOUT`
  
  Maximum time (in milliseconds) a connection can sit idle in the pool.
  
  **Default**: `120000` (2 minutes)
  
  **Example**:
  
  ```properties
  SPRING_DATASOURCE_HIKARI_IDLETIMEOUT=180000
  ```
- `SPRING_DATASOURCE_HIKARI_MAXLIFETIME`
  
  Maximum lifetime (in milliseconds) of a connection in the pool.
  
  **Default**: `1800000` (30 minutes)
  
  **Example**:
  
  ```properties
  SPRING_DATASOURCE_HIKARI_MAXLIFETIME=3600000
  ```
- `SPRING_DATASOURCE_HIKARI_KEEPALIVE_TIME`
  
  Frequency (in milliseconds) of keepalive checks for idle connections.
  
  **Default**: `0` (disabled)
  
  **Example**: Enable keepalive every 5 minutes:
  
  ```properties
  SPRING_DATASOURCE_HIKARI_KEEPALIVE_TIME=300000
  ```
- `SPRING_DATASOURCE_HIKARI_MINIMUMIDLE`
  
  Minimum number of idle connections in the pool.
  
  **Default**: `0` (allows scaling to zero)
  
  **Example**: Maintain at least 5 idle connections:
  
  ```properties
  SPRING_DATASOURCE_HIKARI_MINIMUMIDLE=5
  ```
- `SPRING_DATASOURCE_HIKARI_MAXIMUMPOOLSIZE`
  
  Maximum number of connections in the pool.
  
  **Default**: `15`
  
  **Example**: Increase for high-concurrency deployments:
  
  ```properties
  SPRING_DATASOURCE_HIKARI_MAXIMUMPOOLSIZE=25
  ```
- `SPRING_DATASOURCE_HIKARI_SCHEMA`
  
  Default schema to use for connections.
  
  **Default**: `public`
  
  **Example**:
  
  ```properties
  SPRING_DATASOURCE_HIKARI_SCHEMA=tdk_schema
  ```

## Feign Client Configuration

Settings for HTTP client connections to external services.

- `APP_FEIGN_CONNECT_TIMEOUT`
  
  Connection timeout for Feign clients (in seconds).
  
  **Default**: `10`
  
  **Example**:
  
  ```properties
  APP_FEIGN_CONNECT_TIMEOUT=15
  ```
- `APP_FEIGN_READ_TIMEOUT`
  
  Read timeout for Feign clients (in seconds).
  
  **Default**: `120`
  
  **Example**:
  
  ```properties
  APP_FEIGN_READ_TIMEOUT=180
  ```

## Management & Monitoring

Settings for application health checks and metrics.

- `MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE`
  
  Comma-separated list of management endpoints to expose.
  
  **Default**: `health,metrics,prometheus`
  
  **Example**: Add additional endpoints:
  
  ```properties
  MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE=health,metrics,prometheus,info,env
  ```
- `MANAGEMENT_HEALTH_LDAP_ENABLED`
  
  Enable LDAP health check endpoint.
  
  **Default**: `false`
  
  **Example**:
  
  ```properties
  MANAGEMENT_HEALTH_LDAP_ENABLED=true
  ```

## Sentry Error Tracking

Configuration for Sentry error tracking integration.

- `SENTRY_DSN`
  
  Sentry Data Source Name for error reporting.
  
  **Default**: Empty (disabled)
  
  **Example**:
  
  ```properties
  SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
  ```
- `SENTRY_TRACES_SAMPLE_RATE`
  
  Percentage of traces to capture (0.0 to 1.0).
  
  **Default**: `1.0` (100%)
  
  **Example**: Sample 10% of traces in production:
  
  ```properties
  SENTRY_TRACES_SAMPLE_RATE=0.1
  ```

## Spring Framework Configuration

Advanced Spring Boot settings.

- `SPRING_MAIN_ALLOW_BEAN_DEFINITION_OVERRIDING`
  
  Allow bean definition overriding.
  
  **Default**: `true`
  
  **Example**:
  
  ```properties
  SPRING_MAIN_ALLOW_BEAN_DEFINITION_OVERRIDING=false
  ```
- `SPRING_MAIN_BANNER_MODE`
  
  Control Spring Boot banner display.
  
  **Default**: `off`
  
  **Options**: `off`, `console`, `log`
  
  **Example**:
  
  ```properties
  SPRING_MAIN_BANNER_MODE=console
  ```
- `SPRING_LIQUIBASE_ANALYTICS_ENABLED`
  
  Enable Liquibase analytics.
  
  **Default**: `false`
  
  **Example**:
  
  ```properties
  SPRING_LIQUIBASE_ANALYTICS_ENABLED=true
  ```
- `SPRING_LIQUIBASE_CHANGE_LOG`
  
  Path to Liquibase changelog file.
  
  **Default**: `classpath:db/migration/governor.dbchangelog.xml`
  
  **Example**:
  
  ```properties
  SPRING_LIQUIBASE_CHANGE_LOG=classpath:db/custom-changelog.xml
  ```
- `SPRING_LIQUIBASE_ENABLED`
  
  Enable Liquibase database migrations.
  
  **Default**: `true`
  
  **Example**: Disable for external database management:
  
  ```properties
  SPRING_LIQUIBASE_ENABLED=false
  ```

## See Also

- [CLI Docker Environment Variables](https://docs.synthesized.io/tdk/latest/user_guide/040_reference/environment_variables/docker_environment_variables)
- [Configuration Reference](https://docs.synthesized.io/tdk/latest/user_guide/040_reference/configuration/configuration_reference)