upda/_doc/Configuration.md

Configuration

The following table describe available configuration values.

Variable	Purpose	Default/Description
SECRET	A 32 character long secure random secret used for encrypting some data inside the database. When data has been created inside the database, the secret cannot be changed anymore, otherwise decryption fails.	Not set by default, you need to explicitly set it, e.g., generate via openssl rand -hex 16
TZ	The time zone (recommended to set it properly, background tasks depend on it)	Defaults to Europe/Berlin, can be any time zone according to tz database
AUTH_MODE	The auth mode. Possible values are basic_single and basic_credentials	Defaults to basic_single
BASIC_AUTH_USER	For auth mode basic_single: Username for login	Not set by default, you need to explicitly set it to user name
BASIC_AUTH_PASSWORD	For auth mode basic_single: User's password for login	Not set by default, you need to explicitly set it to a secure random
BASIC_AUTH_CREDENTIALS	For auth mode basic_credentials: list of comma separated credentials, e.g. username1=password1,username2=password2	Not set by default, you need to explicitly set it
DB_TYPE	The database type (Postgres is recommended)	Defaults to postgres, possible values are postgres
DB_SQLITE_FILE	Path to the SQLITE file	Defaults to <XDG_DATA_DIR>/upda/upda.db, e.g. ~/.local/share/upda/upda.db
DB_POSTGRES_HOST	The postgres host	Postgres host address, defaults to localhost
DB_POSTGRES_PORT	The postgres port	Postgres port, defaults to 5432
DB_POSTGRES_NAME	The postgres database name	Postgres database name, needs to be set
DB_POSTGRES_TZ	The postgres time zone	Postgres time zone settings, defaults to Europe/Berlin
DB_POSTGRES_USER	The postgres user	Postgres user name, needs to be set
DB_POSTGRES_PASSWORD	The postgres password	Postgres user password, needs to be set
DB_MIGRATION_ENABLED	See database migration for more detailed information. If true database migrations are executed; useful to disable when multiple instances are spawned	Defaults to true, possible values are true or false
SERVER_PORT	Port	Defaults to 8080
SERVER_LISTEN	Server's listen address	Defaults to empty which equals 0.0.0.0
SERVER_TLS_ENABLED	If server uses TLS	Defaults false
SERVER_TLS_CERT_PATH	When TLS enabled, provide the certificate path
SERVER_TLS_KEY_PATH	When TLS enabled, provide the key path
SERVER_TIMEOUT	Timeout the server waits before shutting down to end any pending tasks	Defaults to 1s (1 second), qualifier can be s = second, m = minute, h = hour prefixed with a positive number
CORS_ALLOW_ORIGINS	CORS configuration	Defaults to *
CORS_ALLOW_METHODS	CORS configuration	Defaults to GET, POST, PUT, PATCH, DELETE, OPTIONS
CORS_ALLOW_HEADERS	CORS configuration	Defaults to Authorization, Content-Type
CORS_ALLOW_CREDENTIALS	CORS configuration	Defaults to true
CORS_EXPOSE_HEADERS	CORS configuration	Defaults to *
LOGGING_LEVEL	Logging level. Possible are debug, info, warn, error, dpanic, panic, fatal. Setting to debug enables high verbosity output.	Defaults to info
LOGGING_ENCODING	Logging encoding. Possible are console and json	Defaults to json
LOGGING_DIRECTORY	Logging directory. When set, logs will be added to a file called upda.log in addition to the standard output. Ensure that upda has access permissions. Use an external program for log rotation if desired.
WEBHOOKS_TOKEN_LENGTH	The length of the token	Defaults to 16, positive number
TASK_UPDATE_CLEAN_STALE_ENABLED	If background task should run to do housekeeping of stale (ignored/approved) updates from the database	Defaults to false
TASK_UPDATE_CLEAN_STALE_INTERVAL	Interval at which a background task does housekeeping by deleting stale (ignored/approved) updates from the database	Defaults to 1h (1 hour), qualifier can be s = second, m = minute, h = hour prefixed with a positive number
TASK_UPDATE_CLEAN_STALE_MAX_AGE	Number defining at which age stale (ignored/approved) updates are deleted by the background task (updatedAt attribute decides)	Defaults to 720h (168 hours = 1 week), qualifier can be s = second, m = minute, h = hour prefixed with a positive number
TASK_EVENT_CLEAN_STALE_ENABLED	If background task should run to do housekeeping of stale (old) events from the database	Defaults to false
TASK_EVENT_CLEAN_STALE_INTERVAL	Interval at which a background task does housekeeping by deleting stale (old) events from the database	Defaults to 8h (8 hours), qualifier can be s = second, m = minute, h = hour prefixed with a positive number
TASK_EVENT_CLEAN_STALE_MAX_AGE	Number defining at which age stale (old) events are deleted by the background task (updatedAt attribute decides)	Defaults to 2190h (2190 hours = 3 months), qualifier can be s = second, m = minute, h = hour prefixed with a positive number
TASK_ACTIONS_ENQUEUE_ENABLED	If background task should run to enqueue matching actions derived from events (actions are invocation separately after being enqueued)	Defaults to true
TASK_ACTIONS_ENQUEUE_INTERVAL	Interval at which a background task does check to enqueue actions	Defaults to 10s (10 seconds), qualifier can be s = second, m = minute, h = hour prefixed with a positive number
TASK_ACTIONS_ENQUEUE_BATCH_SIZE	Number defining how many unhandled events are processed in a batch by the background task	Defaults to 1, must be positive number
TASK_ACTIONS_INVOKE_ENABLED	If background task should run to invoke enqueued actions derived	Defaults to true
TASK_ACTIONS_INVOKE_INTERVAL	Interval at which a background task does check to invoke enqueued actions	Defaults to 10s (10 seconds), qualifier can be s = second, m = minute, h = hour prefixed with a positive number
TASK_ACTIONS_INVOKE_BATCH_SIZE	Number defining how many enqueued actions are processed in a batch by the background task	Defaults to 1, must be positive number
TASK_ACTIONS_INVOKE_MAX_RETRIES	Number defining how often actions are invoked in case of an error, if exceeded, those actions are not retried again	Defaults to 3, must be positive number
TASK_ACTIONS_CLEAN_STALE_ENABLED	If background task should run to do housekeeping of stale (handled, meaning success or error state) actions from the database	Defaults to true
TASK_ACTIONS_CLEAN_STALE_INTERVAL	Interval at which a background task does housekeeping by deleting stale (handled) actions from the database	Defaults to 12h (12 hours), qualifier can be s = second, m = minute, h = hour prefixed with a positive number
TASK_ACTIONS_CLEAN_STALE_MAX_AGE	Number defining at which age stale (handled) actions are deleted by the background task (updatedAt attribute decides)	Defaults to 720h (720 hours = 30 days), qualifier can be s = second, m = minute, h = hour prefixed with a positive number
TASK_PROMETHEUS_REFRESH_INTERVAL	Interval at which a background task updates custom metrics	Defaults to 60s (60 seconds), qualifier can be s = second, m = minute, h = hour prefixed with a positive number
LOCK_REDIS_ENABLED	If locking via REDIS (multiple instances) is enabled. Requires REDIS. Otherwise uses in-memory locks.	Defaults to false
LOCK_REDIS_URL	If locking via REDIS is enabled, this should point to a resolvable REDIS instance, e.g. redis://<user>:<pass>@localhost:6379/<db>.
PROMETHEUS_ENABLED	If Prometheus metrics are exposed	Defaults to false
PROMETHEUS_METRICS_PATH	Defines the metrics endpoint path	Defaults to /metrics
PROMETHEUS_SECURE_TOKEN_ENABLED	If Prometheus metrics endpoint is protected by a token when enabled (recommended)	Defaults to true
PROMETHEUS_SECURE_TOKEN	The token securing the metrics endpoint when enabled (recommended)	Not set by default, you need to explicitly set it to a secure random
WEB_API_URL	Base URL of API, e.g. https://upda.domain.tld	http://localhost
WEB_TITLE	The title of the frontend page	upda

Database migration

By default, upda runs database migrations (DB_MIGRATION_ENABLED) to create the necessary database schema it uses. You can disable this behavior by setting it to false which might be useful if you have multiple instances running and only one should (regularly) update the database schema. Please make sure that this instance has the highest priority when updating upda and it should also start before all other (updated) instances start. If you have multiple instance and keep the default that all instances run migrations, some instances might fail to start as they apply locking when migrating database schema and conflict with other instances while migration is being executed.