Configuration

Every Caliper SDK repository has a configuration file, by default located at configuration/settings.py – you can override this location via the environment variable Q2SDK_SETTINGS_MODULE.

Our defaults will serve most common use cases, but this page is dedicated to explaining the available settings.

REGISTRATION

These settings change how your code is made available at runtime:

INSTALLED_EXTENSIONS

Default
[]

List of strings that will be imported as extensions on q2 run q2 create_extension will automatically append new extensions to this list

INSTALLED_ENTRYPOINTS

Default
[]

List of strings that will be registered at the CLI q2 create_entrypoint will automatically append new extensions to this list

CUSTOM_CORES

Default
{}

Key/Value pairs where key=Name of the core and value=path to the core_object q2 create_coreflow will automatically append new items to this dictionary

UDP_HANDLERS

Default
{}

If FORK_REQUESTS is True, the parent process will not know much about the child processes. However, it is useful for the children to communicate with the parent about certain runtime concerns– metrics, ‘last success time’ for healthchecks, etc. This is accomplished using a UDP server that is booted up alongside the existing HTTP one.

Using this, you can send messages to the server using the q2sdk.core.non_http_handlers.udp.writer.send_msg. This takes a msg_type and a msg. Next, register a function to handle it in the parent by defining a key/value pair in this variable, where {key} is the msg_type and {value} is the reference to the function to run:
UDP_HANDLERS = {
    'IncrementCount': increment_count
}
Note the missing () on increment_count. We are not invoking the function, just referencing it to be invoked at a later time.

CORE

Default
None

This can either be the name of a core included in the q2_cores package, or the name of a core that you have built.

DISABLED_DEFAULT_EXTENSIONS

Default
[]

Rarely, you may want to disable a default extension that the Caliper SDK provides. Adding them to this list will do so. This should not be done without good reason.

ALLOW_TRAFFIC_TO_DEFAULT_EXTENSIONS

Default
[]

You may want to allow non Q2 traffic to a default extension, like the /status endpoint. Adding that extension name to this list will allow non Q2 traffic to the extension.

SERVER SETTINGS

These settings affect how the Caliper SDK server (q2 run) behaves:

FORK_REQUESTS

Default
False

Environment Variable
Q2SDK_FORK_REQUESTS

If True, new requests will be served on a new PID after an os fork, rather than in a new thread of the current process.

This is less memory-efficient, but has some benefits:

Shared memory between requests is disabled by default (see below for clarification)

Calls cannot block other calls. This can potentially happen in servers with VERY high counts of incoming or outgoing HTTP traffic.

COMPRESS_RESPONSE

Default
False

Environment Variable
Q2SDK_COMPRESS_RESPONSE

If True, will gzip the responses if the caller sets Accept-Encoding: gzip header. If the server is running behind and nginx or other proxy server, this may be unnecessary as the proxy server will likely take care of this.

MAX_CONNECTIONS

Default
128

Environment Variable
Q2SDK_MAX_THREADS

The number of simultaneous connections allowed in asyncio background threads.

GLOBAL_LOGGING_FILTERS

Default
PasswordFilter, TaxIDFilter (None if DEBUG mode enabled)

Python log filter objects that will be applied to EVERY log line, across all extensions. It is also possible to do this at an extension level with the LOGGING_FILTERS static variable on the RequestHandler class.

GLOBAL_PERIODIC_JOB_LOGGING_FILTERS

Default
GLOBAL_LOGGING_FILTERS + CreditCardFilter (None if DEBUG mode enabled)

Python log filter objects that will be applied to EVERY periodic entrypoint. It is also possible to do this at an extension level with the LOGGING_FILTERS static variable on the Entrypoint class.

LOG_LINE_LIMIT

Default
1048576 (1 Mb)

Environment Variable
Q2SDK_LOG_LINE_LIMIT

At what length should a log line be split into multiple lines

DEV_SOCKET_URL

Default
None

Environment Variable
Q2SDK_DEV_SOCKET_URL

If set, will attempt to connect to a websocket server to forward traffic back to your running server. Requires authentication with a token using q2 login

DEV_PORTAL_TOKEN_URL

Default
https://q2developer.com/oauth2/token

Environment Variable
Q2SDK_DEV_PORTAL_TOKEN_URL

Where to authenticate to get a short lived jwt for the DEV_SOCKET_URL above. The default value uses the Q2DEVELOPER_URL variable as the base URL.

Q2DEVELOPER_URL

Default
https://q2developer.com

Environment Variable
Q2DEVELOPER_URL

URL for the Q2 Developer website.

Q2DEVELOPER_API_URL

Default
https://q2developer.com/api/v1

Environment Variable
Q2DEVELOPER_API_URL

URL for the Q2 Developer API. The default value uses the Q2DEVELOPER_URL variable as the base URL.

Q2SDK_REPO_NAME

Default
None

Environment Variable
Q2SDK_REPO_NAME

Will autodetect the name of repo from .git/config file if not overridden, falling back to ‘unknown’

MULTITENANT

Default
False

For use with Caliper SDK repositories that will serve multiple FIs. When set, this will ensure HQ Credentials are never read from environment variables, only from Vault. This ensures the behavior of the SDK server in development mode will function identically when running in the Q2 datacenter. To use this, ensure a local vault directory is set up via “q2 vault add_hq_creds_multi”.

SECURITY

INBOUND_IP_WHITELIST

Default
[]

Environment Variable
Q2SDK_IP_WHITELIST (comma delimited)

Most traffic will originate from inside the Q2 network, but if you are exposing an endpoint via an Ardent Handler, this will allow only the known IPs listed here. It is also possible to do this at an extension level with the INBOUND_IP_WHITELIST static variable on the RequestHandler class.

DANGEROUS_WHITELIST

Default
[]

Some networking methods can be insecure, if used improperly. This lets the developer explicitly opt into their use.

SSL_CERTIFICATE

Default
None

Environment Variable
Q2SDK_SSL_CERT

Used to enable HTTPS traffic on ANTILLES_SERVER_HTTPS_PORT.

SSL_KEY

Default
None

Environment Variable
Q2SDK_SSL_KEY

Used to enable HTTPS traffic on ANTILLES_SERVER_HTTPS_PORT.

SERVE_ASSETS_HTTPS

Default
False

Environment Variable
Q2SDK_SERVE_ASSETS_HTTPS

Auto-defined when deployed. If True, will look for certificates and serve over HTTPS.

SERVE_ASSETS_ON_LOCALHOST

Default
False

Environment Variable
Q2SDK_SERVE_ASSETS_ON_LOCALHOST

If True, frontend assets will be requested from localhost:{ANTILLES_SERVER_PORT}.

VAULT_SCOPED_READ

Default
False

Environment Variable
Q2SDK_VAULT_SCOPED_READ

The original SDK implementation to read from the Vault secret store didn’t have any guard rails. The newer method scopes reads to a more specific location for each running service. This is absolutely preferred, but must be opted into for backwards compatibility reasons.

VAULT_CACHE_READS

Default
True

Environment Variable
Q2SDK_VAULT_CACHE_READS

If True, vault calls will cache reads in memcached for up to VAULT_EXPIRY seconds

VAULT_EXPIRY

Default
60 (seconds)

Environment Variable
Q2SDK_VAULT_EXPIRY

Length of time for which a vault secret is cached.

VAULT_ENCRYPTION_KEY

Default
md5 sum of the service name

Environment Variable
Q2SDK_VAULT_ENCRYPTION_KEY

Key with which to encrypt vault secrets in cache.

Q2MSG_KEYS_PATH

Default
.antilles/q2msg_keys.json

Environment Variable
Q2MSG_KEYS_PATH

Used for encrypting/decrypting messages between internal Q2 services. Will be set dynamically in the datacenter pulled from vault.

CONNECTIONS

Settings used for authentication with various services.

HQ_CREDENTIALS

Default
HqCredentials object

Environment Variables:
HQ_URL, CSR_USR, CSR_PWD, ABA

If environment_variables are not set, will read from VAULT_KEY location.

SMART_TOKEN

Default
None

Environment Variable
SMART_TOKEN

If this environment variable is not set, it will be pulled from Vault.

SMART_URL

Default
None

Environment Variable
Q2SDK_SMART_URL

VAULT_KEY

Default
Same as ABA

Environment Variable
VAULT_KEY

See Vault in the guides section of the documentation.

VAULT_LOCAL_DIR

Default
None

Environment Variable
Q2SDK_VAULT_LOCAL_DIR

If set, will read vault data from a local folder. Used for local testing ONLY

VAULT_DEFAULT_PREFIX

Default
secret/ABA

Environment Variable
Q2SDK_VAULT_PREFIX

NOMAD_SECRETS_DIR

Default
None

Environment Variable
NOMAD_SECRETS_DIR

In the Q2 Datacenter, this will be set for you as a local disk directory where vault secrets can be stored to avoid the networking round trip

KRAYT_URL

Default
None

Environment Variable
Q2SDK_KRAYT_URL

Krayt is an http layer written by Q2 over the Kafka message bus.

KRAYT_ENVSTACK

Default
KRAYT-DEMO

Environment Variable
Q2SDK_KRAYT_ENVSTACK

This variable refers to a key stored in Vault that will be used to encrypt and decrypt all messages. This differs on an FI basis and is often something like 1234-01 in reality, but will be set for you on deployment.

MOCK_KRAYT_CALLS

Default
{DEBUG}

Environment Variable
Q2SDK_MOCK_KRAYT

ENABLE_OPEN_TELEMETRY

Default
False locally. True in the datacenter

Environment Variable
Q2SDK_ENABLE_OPEN_TELEMETRY

If enabled metrics will be submitted to an open telemetry collector. Enables all opentelemetry environment variables: https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/#general-sdk-configuration

FLUENT_LOGGER_ENABLE

Default
False locally. True in the datacenter

Environment Variable
Q2SDK_FLUENT_LOGGER_ENABLE

If enabled logs will be submitted to fluentd using a native log shipper

FLUENT_LOGGER_TAG

Default
Null locally. Populated in the datacenter

Environment Variable
Q2SDK_FLUENT_LOGGER_TAG

FLUENT_LOGGER_HOST

Default
Null locally. Populated in the datacenter

Environment Variable
Q2SDK_FLUENT_LOGGER_HOST

FLUENT_LOGGER_PORT

Default
Null locally. Populated in the datacenter

Environment Variable
Q2SDK_FLUENT_LOGGER_PORT

FLUENT_LOGGER_KVS

Default
Null locally. Populated in the datacenter

Environment Variable
Q2SDK_FLUENT_LOGGER_KVS

Additional fields to be passed with all fluent log lines, formatted as key1=value1,key2=value2. All attribute values MUST be considered strings and characters outside the baggage-octet range MUST be percent-encoded.

FLUENT_LOGGER_COMPRESSION_THRESHOLD

Default
Null locally. Populated in the datacenter

Environment Variable
Q2SDK_FLUENT_LOGGER_COMPRESSION_THRESHOLD

Threshold after which messages will be compressed before transport

ENVIRONMENT MAPPINGS

These settings direct your extensions to behave differently depending on environment. They will function appropriately once deployed inside the Q2 datacenter.

DEPLOY_ENV

Default
DEV

Environment Variable
DEPLOY_ENV

Will be set to DEV/STG/PROD depending on the environment.

RETURN_TABLE_OBJECTS_FROM_DB

Default
False

Environment Variable
Q2SDK_RETURN_TABLE_OBJECTS_FROM_DB

When True, used to make calls to the DB return a list of TableRow objects instead of ObjectifiedElement objects

ARDENTFS_URL

Default
''

Environment Variable
Q2SDK_ARDENTFS_URL

Used for file upload functionality.

ARDENTFS_BUCKET

Default
{VAULT_KEY}

Used for file upload functionality.

SERVICE_NAME

Default
None

Environment Variable
Q2SDK_SERVICE_NAME

Auto-defined when deployed. Used for building an asset URL endpoint when behind a load balancer.

IMAGE_TAG

Default
None

Environment Variable
Q2SDK_IMAGE_TAG

Auto-defined when deployed. Used for building an asset URL endpoint when behind a load balancer.

BASE_ASSET_URL

Default
None

Environment Variable
Q2SDK_ASSET_BASE_URL

Auto-defined when deployed. Used for building an asset URL endpoint when behind a load balancer.

TREAT_CURRENCY_AS_DECIMAL

Default
False

Environment Variable
Q2SDK_TREAT_CURRENCY_AS_DECIMAL

Currency values returned from HQ will be the Decimal data type instead of float. Highly recommended to set to True if doing any arithmetic with currency values in order to prevent rounding errors.

TOPIC_BY_ENV

Default
sdk topic names

Kafka Topics to use for message bus extensions

SMART_TOPIC_BY_ENV

Default
smart trait topic names

Kafka Topics to use for q2_smart traits

ERROR_TOPIC_BY_ENV

Default
sdk error topic names

Kafka Topics to use for message bus extensions when messages fail processing

DEVELOPMENT ASSISTANCE

DEBUG

Default
True

Environment Variable
Q2SDK_DEBUG

Will intercept core calls, automatically bounce hq when deploying, and generally make development faster and safer. Will be set to True in development environments, but False in the datacenter.

LOCAL_DEV

Default
True

Environment Variable
Q2SDK_LOCAL_DEV

False if the NOMAD_ALLOC_ID environment variable is present. Basically if it’s deployed in the datacenter.

ASSET_URL_OVERRIDE

Default
{}

Useful in development, when you have more than one frontend application running on a distinct port. For instance:
{
    'Foo': 'http://localhost:3000',
    'Bar': 'http://localhost:3001'
}

OUTBOUND_WHITELIST

Default
['localhost', 'q2ebanking.com', 'fabio-hq-lb']

Effective only when DEBUG is True. Alerts the developer that a support ticket must be made before deploying to the datacenter.

Q2REQUESTS_DEFAULT_TIMEOUT

Default
30

Environment Variable
Q2SDK_DEFAULT_REQUEST_TIMEOUT

Time q2_request calls will wait for a server to return a response. Corresponds to timeout in Request docs: https://2.python-requests.org/en/master/user/advanced/#timeouts

Q2REQUESTS_DEFAULT_CONNECT_TIMEOUT

Default
5

Environment Variable
Q2SDK_DEFAULT_REQUEST_CONNECT_TIMEOUT

Time q2_request calls will wait to establish a connection

ASYNCIO_DEBUG

Default
{DEBUG}

Environment Variable
Q2SDK_ASYNCIO_DEBUG

If True, will alert the developer to blocking calls, un-awaited coroutines, etc.

ASYNCIO_SLOW_THRESHOLD

Default
1

Environment Variable
Q2SDK_ASYNCIO_SLOW_THRESHOLD

Call duration allowed, in seconds, before a blocking call will be reported.

MOCK_BRIDGE_CALLS

Default
{DEBUG}

Environment Variable
Q2SDK_MOCK_BRIDGE

STACK_BOUNCE_URL

Default
None

Environment Variable
Q2SDK_STACK_BOUNCE_URL

In development environments, this is used by q2 bounce_stack.

FORM_INSTALL_BASE_URL

Default
None

Environment Variable
FORM_INSTALL_BASE_URL

Used during q2 install.

USE_SLASH_FOR_INSTALL_PORT

Default
False

Environment Variable
Q2SDK_SLASH_FOR_INSTALL_PORT

Used to force an instance to navigate to {url}/1980 instead of {url}:1980 in order to utilize a load balancer such as nginx.

ARDENT_URL

Default
''

Environment Variable
Q2SDK_ARDENT_URL

Used by ardent module for calling the /refreshCache endpoint, among others.

INSIGHT_URL_DC

Default
https://tp_productionreport.q2dc.local/Prod/RestAPI/FIInfoAPI

Environment Variable
Q2INSIGHT_DC_URL

Used by q2 insight CLI tool.

HOLOCRON_DEV_URL

Default
https://ingress-private.service.use1.dev.aws.consul/holocron/awsdev/kraytd/holocron

Environment Variable
Q2SDK_HOLOCRON_DEV_URL

Used by the Holocron object in the holocron.py file to fetch information from Holocron in the corporate environment

HOLOCRON_STAGE_URL

Default
https://ingress-private.service.use1.stg.aws.consul/holocron/awsstg/kraytd/holocron

Environment Variable
Q2SDK_HOLOCRON_STAGE_URL

Used by the Holocron object in the holocron.py file to fetch information from Holocron in the staging environment

HOLOCRON_PROD_URL

Default
https://ingress-private.service.use1.prd.aws.consul/holocron/awsprd/kraytd/holocron

Environment Variable
Q2SDK_HOLOCRON_PROD_URL

Used by the Holocron object in the holocron.py file to fetch information from Holocron in the production environment

PINION_DEV_URL

Default
https://ingress-private.service.dev.aws.consul/pinion-producer-awsdev/kraytd

Environment Variable
Q2SDK_PINION_DEV_URL

Used by the Pinion object in the pinion.py file to interact with Pinion in the corporate environment

PINION_STAGE_URL

Default
https://ingress-private.service.stg.aws.consul/pinion-producer-awsstg/kraytd

Environment Variable
Q2SDK_PINION_STAGE_URL

Used by the Pinion object in the pinion.py file to fetch information from Pinion in the staging environment

PINION_PROD_URL

Default
https://ingress-private.service.prd.aws.consul/pinion-producer-awsprd/kraytd

Environment Variable
Q2SDK_PINION_PROD_URL

Used by the Pinion object in the pinion.py file to fetch information from Pinion in the production environment

FIREBASE_DEV_URL

Default
https://ingress-private.service.dev.aws.consul/pinion-producer-awsdev/kraytd

Environment Variable
Q2SDK_FIREBASE_DEV_URL

Used by the PushNotification object in the models/push_notification.py file to interact with the NDS (Notification Delivery Service) in the corporate environment

FIREBASE_STAGE_URL

Default
https://ingress-private.service.stg.aws.consul/pinion-producer-awsstg/kraytd

Environment Variable
Q2SDK_FIREBASE_STAGE_URL

Used by the PushNotification object in the models/push_notification.py file to interact with the NDS (Notification Delivery Service) in the staging environment

FIREBASE_PROD_URL

Default
https://ingress-private.service.prd.aws.consul/pinion-producer-awsprd/kraytd

Environment Variable
Q2SDK_FIREBASE_PROD_URL

Used by the PushNotification object in the models/push_notification.py file to interact with the NDS (Notification Delivery Service) in the production environment

ANTILLES_SERVER_PORT

Default
1980

Environment Variable
ANTILLES_SERVER_PORT

The port q2 run will use when running via HTTP.

ANTILLES_SERVER_HTTPS_PORT

Default
1981

Environment Variable
ANTILLES_SERVER_HTTPS_PORT

The port q2 run will use when running via HTTPS.

ANTILLES_UDP_CALLBACK_PORT

Default
Random available port

Environment Variable
ANTILLES_UDP_CALLBACK_PORT

The port the UDP server will use when FORK_REQUESTS is True.

FE_FILE_EXTENSIONS_TO_RELOAD

Default
['js', 'ts', 'html', 'scss', 'css', 'json']

q2 run will attempt to rebuild frontend assets when files with the listed file extensions are modified.

FE_FILE_PATH_TO_IGNORE

Default
['dist', 'node_modules', '.lock', 'package-lock.json']

Prevents rebuild of frontend assets in listed directories.

VERIFY_HQ_CERT

Default
True

Some older development HQs have invalid certificates installed. Setting this to False will bypass the missing cert until the HQ is patched.

USE_INCOMING_HQ_URL

Default
True

Environment Variable
Q2SDK_USE_INC_HQ

Most of the time HQ is on the same network as the SDK server. If not, this can help determine the correct URL.

DISABLE_BROWSER_LINK

Default
False

Environment Variable
Q2SDK_DISABLE_BROWSER_LINK

Browser Link refers to the websocket connection the SDK server uses if an extension is served through UUX Online Banking.

LOG_RESPONSE_IN_DEBUG

Default
False

Environment Variable
Q2SDK_LOG_RESPONSE

If True, will log a debug level message of the server response

ENABLE_LOG_REPLAY

Default
False in LOCAL_DEV, True otherwise

Environment Variable
Q2SDK_ENABLE_LOG_REPLAY

If True, will buffer log lines as they are written, replaying them at the end of a 500 request, regardless of log level. Useful if the server is at INFO mode (production), but the relevant logs to track the problem are written in DEBUG level.

CUSTOM_CHECKS

Default
[]

List of CustomCheck subclasses that will be run when q2 check is executed. See Adding Custom Checks for more information.

REPORTING

REPOSITORY_VERSION

Default
Unreleased

Will be displayed in /inspect endpoint. Updated with q2 changelog.

IS_CUSTOMER_CREATED

Default
True

Improves production issue triage by categorizing the authorship of the code.

INCLUDE_QUERY_PARAMS_IN_LOGS

Default
True

Environment Variable
Q2SDK_INCLUDE_QUERY_PARAMS_IN_LOGS

If True, will include query parameters for GET requests in the extension name in log files.

DATABASES

We support both SQL_SERVER and POSTGRES servers, though, for the most part, this is only for development.

DATABASES.SQL_SERVER.HOST

Default
None

Environment Variable
SQL_SERVER_HOST

DATABASES.SQL_SERVER.NAME

Default
None

Environment Variable
SQL_SERVER_NAME

DATABASES.SQL_SERVER.USER

Default
None

Environment Variable
SQL_SERVER_USER

DATABASES.SQL_SERVER.PASSWORD

Default
None

Environment Variable
SQL_SERVER_PWD

DATABASES.POSTGRES.HOST

Default
None

Environment Variable
POSTGRES_HOST

DATABASES.POSTGRES.NAME

Default
None

Environment Variable
POSTGRES_NAME

DATABASES.POSTGRES.USER

Default
None

Environment Variable
POSTGRES_USER

DATABASES.POSTGRES.PASSWORD

Default
''

Environment Variable
POSTGRES_PWD

DATABASES.POSTGRES.PORT

Default
5432

Environment Variable
POSTGRES_PWD

CACHE

Settings related to built-in caching functionality. See Caching in the guides section of the documentation.

CACHE.PREFIX

Default
SERVICE_NAME or VAULT_KEY

CACHE.HOST

Default
mchq-dev.service.q2consul-corp

Environment Variable
CACHE_HOST

CACHE.PORT

Default
11211

Environment Variable
CACHE_PORT

CACHE.CONNECT_TIMEOUT

Default
1

CACHE.TIMEOUT

Default
1

CACHE.COMPRESS_DATA

Default
True

CACHE.ENCRYPTION_KEY

Default
None

If set, data will be encrypted using the given key.

CACHE.KEYS_TO_REMEMBER

Default
100

This refers to how many items will show up in the /cache endpoint. It does NOT affect how much data can be stored in cache.

BLOCKED_AUDIT_ACTIONS

Default
["ExecuteWedgeRequest"]

These are Audit Actions that can cause problems if installed for an Audit Action extension.