Configuration

Configuration is provided via environment variables or a YAML config file (default: /etc/koala/config.yml).

Configuration Precedence

Configuration values are resolved in the following order (highest priority first):

1. Environment variables — Always take precedence over config file values
2. YAML config file — Loaded from /etc/koala/config.yml or ~/.koala/config.yml
3. Defaults — Hardcoded defaults in the code

Environment variables can override any value from the config file. This is useful for sensitive data (passwords, keys) that should not be stored in config files.

YAML Config File

The YAML config file uses a hierarchical structure with categories:

default:
  app_name: koala
  koala_name: "My Koala Instance"
  workarea_base_path: /dias/workarea

loader:
  errorarea: /dias/errorarea
  delete_sip_on_error: false

database:
  host: localhost
  port: 3306
  name: koala
  user: koala
  password: secret

Each top-level key becomes a prefix for environment variable names. For example, default.app_name maps to the environment variable DEFAULT_APP_NAME.

Environment Variables

Cache (Redis)

Name	Type	Default	Description
CACHE_HOST	string	—	Redis hostname or IP

Database (MySQL)

Name	Type	Default	Description
DATABASE_CONNECTION_STRING	string	—	MySQL connection string
MYSQL_DATABASE	string	—	MySQL database name
MYSQL_PASSWORD	string	—	MySQL application password
MYSQL_ROOT_PASSWORD	string	—	MySQL root password
MYSQL_USER	string	—	MySQL application user
KOALA_MYSQL_HOST	string	—	MySQL hostname (legacy)

Message Queue (RabbitMQ)

Name	Type	Default	Description
MQ_HOST	string	—	RabbitMQ hostname or IP
MQ_PORT	int	—	RabbitMQ protocol port
MQ_USER	string	—	RabbitMQ username
MQ_PW	string	—	RabbitMQ password
MQ_API_PORT	string	—	RabbitMQ REST API port
RABBITMQ_DEFAULT_USER	string	—	RabbitMQ default user
RABBITMQ_DEFAULT_PASS	string	—	RabbitMQ default password

Scheduler

Name	Type	Default	Description
SCHEDULER_PRELOADAREA	string	—	Upload area path (hotfolder for SIPs)
SCHEDULER_SIP_FILE_PATTERN	string	—	Regex pattern to recognize new SIP files
SCHEDULER_SCHEDULED_FILE_EXTENSION	string	—	File extension marking queued SIPs
SCHEDULER_INTERVAL_IN_SEC	int	—	Interval (seconds) between upload area scans
SCHEDULER_INGEST_QUEUE	string	—	RabbitMQ ingest queue name
SCHEDULER_INGEST_ROUTING_KEY	string	—	RabbitMQ ingest routing key
SCHEDULER_CREATE_INGEST_TICKET	bool	false	Create ingest ticket when scheduler touches a SIP

Loader

Name	Type	Default	Description
LOADER_ERRORAREA	string	—	Path to error area (moved SIPs on failure)
LOADER_DELETE_SIP_ON_ERROR	bool	false	Delete SIP instead of moving to errorarea
LOADER_AIP_MAX_FILE_COUNT	string	—	Maximum allowed file count in an AIP
LOADER_SIP_MAX_FILENAME_LENGTH	string	—	Maximum filename length in SIP (if set)
LOADER_USE_7ZIP	bool	false	Use 7zip for packing/unpacking instead of internal implementation
LOADER_7ZIP_PATH	string	—	Path to 7zip binary (if LOADER_USE_7ZIP=true)
LOADER_USE_BLOCKSIZE	int	—	Blocksize in bytes for file hashing
LOADER_CHECK_URN8141_FORMAT	bool	false	Validate external_asset_id against RFC 8141 format
LOADER_CLAMAV_ENABLED	bool	false	Enable virus scanning with ClamAV
LOADER_CLAMAV_SOCKET	string	/run/clamav/clamd.sock	Unix socket for ClamAV communication
LOADER_CLAMAV_CONTINUE_ON_ERROR	bool	false	Continue ingest if ClamAV connection fails
LOADER_CIRCUIT_BREAKER_ENABLED	bool	false	Automatically pause scheduler on repeated errors
LOADER_CIRCUIT_BREAKER_EXCEPTION_TYPE_MAX_FAILED_COUNT	int	—	Max errors before circuit opens
LOADER_CIRCUIT_BREAKER_EXCEPTION_TYPE_EXPIRATION_IN_SEC	int	—	Time before circuit resets
LOADER_CALLBACK_URL	string	—	HTTP POST callback URL triggered after ingest success or failure

Retriever

Name	Type	Default	Description
RETRIEVER_DOWNLOADAREA	string	—	Download area for DIPs
RETRIEVER_DIP_FILENAME	string	—	Default DIP filename
RETRIEVER_DISABLE_DIP_AGENT_OVERWRITE	bool	false	Preserve original metsHdr/agent values in DIP
RETRIEVER_FRONTEND	string	—	Base URL prepended to DIP download paths
RETRIEVER_RETRIEVE_QUEUE	string	—	RabbitMQ retrieve queue name
RETRIEVER_RETRIEVE_ROUTING_KEY	string	—	RabbitMQ retrieve routing key
RETRIEVER_WEBSERVER_RELATIVE_ALIAS	string	—	URI segment for web server directory listing

Purger

Name	Type	Default	Description
PURGER_HIGH_WATERMARK_IN_PERCENTAGE	string	—	Disk usage % triggering space reclamation
PURGER_LOW_WATERMARK_IN_PERCENTAGE	string	—	Disk usage % stopping reclamation
PURGER_RETENTION_TIME_IN_MINUTES	int	—	Minimum time DIPs stay in download area
PURGER_INTERVAL_IN_SEC	int	—	Purger check interval (seconds)
PURGER_CLEANUP_ERRORAREA_ENABLED	bool	false	Enable automatic errorarea cleanup

Archival Storage (LTP)

Name	Type	Default	Description
LTP_IMPLEMENTATION	string	—	Archival storage backend (tsm or nfshsm)
LTP_AIP_BASE_NAME	string	aip	Base filename for AIP archives
LTP_AIP_FORMAT	string	zip	AIP archive format (zip, tar, etc.)
LTP_OPTIMIZE_FOR_ZIP	bool	false	Use SIP from uploadarea directly as AIP (skips repacking)
LTP_TSM_FILESPACE	string	kopal	IBM Spectrum Protect filespace name
LTP_NFSHSM_AIP_FOLDER	string	—	NFS/HSM base folder path (if LTP_IMPLEMENTATION=nfshsm)

Metadata Index (MDQI / BaseX)

Name	Type	Default	Description
MDQI_BASEX_URL	string	—	BaseX REST API endpoint
MDQI_BASEX_USER	string	—	BaseX username
MDQI_BASEX_PW	string	—	BaseX password
MDQI_INDEX_WHILE_INGEST	bool	true	Index metadata in BaseX during ingest
MDQI_BASEX_CREATE_INDEXES	bool	true	Create text/attribute indexes for new BaseX databases

Email (SMTP)

Name	Type	Default	Description
DEFAULT_SMTP_HOST	string	—	SMTP relay hostname
DEFAULT_SMTP_PORT	int	—	SMTP port
DEFAULT_SMTP_USER	string	—	SMTP username
DEFAULT_SMTP_PW	string	—	SMTP password
DEFAULT_SMTP_FROM	string	—	Email sender address
DEFAULT_SMTP_TO	string	—	Email recipient(s)
DEFAULT_SEND_MAIL_ON_ERROR	bool	false	Send email on ingest/retrieve error
DEFAULT_SEND_MAIL_ON_SUCCESS	bool	false	Send email on successful ingest
DEFAULT_SEND_MAIL_ON_NO_INGESTS	bool	false	Send email when no new ingests occur
DEFAULT_NO_INGESTS_EMAIL_TO	string	—	Recipient for no-ingests alert
DEFAULT_NO_INGESTS_MAX_TIMESPAN_IN_MINUTES	int	—	Minutes without ingests before alerting

Web UI

Name	Type	Default	Description
WEB_SECRET_KEY	string	—	Secret key for Flask sessions
WEB_HTTP_BASIC_AUTH_REQUIRED	bool	false	Require HTTP Basic Auth for API endpoints
WEB_API_QUERY_AUTH_REQUIRED	string	—	DIAS spec: require passwords in URLs
WEB_LDAP_ENABLE	bool	false	Enable LDAP authentication
WEB_LDAP_HOST	string	—	LDAP server hostname
WEB_LDAP_PORT	int	—	LDAP port
WEB_LDAP_USE_SSL	bool	false	Use SSL for LDAP connection
WEB_LDAP_BASE_DN	string	—	Base DN for user search
WEB_LDAP_FILTER	string	—	LDAP search filter
WEB_LDAP_ADMIN_DN	string	—	LDAP admin DN
WEB_LDAP_ADMIN_PW	string	—	LDAP admin password
WEB_SSO_ENABLED	bool	false	Enable OpenID Connect (SSO) authentication
WEB_SSO_ISSUER	string	—	OIDC issuer URL
WEB_SSO_AUTHORIZATION_ENDPOINT	string	—	OIDC authorization endpoint
WEB_SSO_TOKEN_ENDPOINT	string	—	OIDC token endpoint
WEB_SSO_USERINFO_ENDPOINT	string	—	OIDC userinfo endpoint
WEB_SSO_JWKS_URI	string	—	OIDC JWKS document URL
WEB_SSO_CLIENT_ID	string	—	OIDC client ID
WEB_SSO_CLIENT_SECRET	string	—	OIDC client secret
WEB_SSO_SCOPE	string	—	OIDC scope
WEB_SSO_PROTO	string	—	Protocol (http/https) for client callbacks

Application

Name	Type	Default	Description
DEFAULT_APP_NAME	string	—	Application name (unique, used for container identification)
DEFAULT_KOALA_NAME	string	—	Display name for this koala installation
DEFAULT_WORKAREA_BASE_PATH	string	—	Base path for loader/retriever working directories
DEFAULT_HEARTBEAT_INTERVAL_IN_SEC	int	—	Heartbeat interval (seconds)
DEFAULT_GROWTH_WIDGET_ENABLED	bool	false	Enable dashboard widget showing monthly ingest stats
DEFAULT_USAGE_CONSUMPTION_SEND_MAIL	bool	false	Send monthly mass storage statistics email
DEFAULT_USAGE_CONSUMPTION_EMAIL_TO	string	—	Recipient for storage statistics email

SFTP / FTP Info

Name	Type	Default	Description
FTPINFO_PASSWORD	string	—	Password for SFTP user
FTPINFO_PRELOAD_AREA	string	—	Path to upload area in SFTP container
FTPINFO_SERVER	string	—	Hostname or IP of SFTP upload server
FTPINFO_SSHKEY	string	—	SSH public key for SFTP key-based authentication
FTPINFO_USER	string	—	SFTP username
DEFAULT_FTP_INFO_STATUS	string	—	Disable ftpinfo endpoints (optional)

Required vs Optional

Required Variables

These variables must be set for koala to start:

Variable	Description
DATABASE_CONNECTION_STRING	MySQL connection string
MQ_HOST	RabbitMQ hostname
MQ_USER	RabbitMQ username
MQ_PW	RabbitMQ password
CACHE_HOST	Redis hostname
DEFAULT_WORKAREA_BASE_PATH	Base path for working directories
LTP_IMPLEMENTATION	Storage backend (tsm or nfshsm)

Optional Variables

All other variables have sensible defaults and can be omitted. Commonly overridden optional variables:

Variable	Default	When to override
LOADER_CALLBACK_URL	—	When you want webhook notifications
LOADER_CLAMAV_ENABLED	false	When virus scanning is desired
WEB_SSO_ENABLED	false	When using OIDC authentication
WEB_LDAP_ENABLE	false	When using LDAP authentication
DEFAULT_SEND_MAIL_ON_ERROR	false	When email alerts are desired
LTP_OPTIMIZE_FOR_ZIP	false	When storing ZIP SIPs directly

Validation

koala performs minimal runtime validation of configuration values. Invalid values typically result in:

• Connection failures — Wrong database/MQ/Redis credentials cause startup errors
• Silent defaults — Missing optional variables fall back to hardcoded defaults
• Type errors — Boolean/string confusion may cause unexpected behavior

Always verify configuration by checking application logs on startup. Look for lines like:

local_settings[loader_callback_url]=https://example.com/callback

These confirm that environment variables were loaded correctly.