Skip to main content

Environment variables

Learn how to configure Piiano Vault using environment variables

You can set environment variables to configure Piiano Vault, which take precedence over the configuration file of the Piiano Vault settings.


The Set configuration variable REST API call and Set configuration variable CLI command enable some environment variables to be configured dynamically. Refer to the REST API or CLI documentation for details of the supported environment variables.

Piiano Vault license

NameTypeDefault (Dev / Server)EditionDetails
PVAULT_SERVICE_LICENSEstringnoneAllA valid Piiano Vault license is required to start your Vault. The license is a string of characters. See License management for more information.

Production and development mode

PVAULT_DEVMODEbooltrue for pvault-dev

false otherwise
AllWhether Vault runs in development mode. This setting also determines the default values for several environment variables.

Variables whose default values depend on PVAULT_DEVMODE

If PVAULT_DEVMODE is true, these variables override the defaults set by development mode.

NameDefault when PVAULT_DEVMODE is trueDefault when PVAULT_DEVMODE is false


NameTypeDefault (Dev / Server)EditionDetails
PVAULT_DB_HOSTNAMEstring"localhost"AllHostname of the running database
PVAULT_DB_NAMEstring"pvault"AllName of the database to connect to
PVAULT_DB_USERstring"pvault"AllUsername for the database
PVAULT_DB_PASSWORDstring"pvault"AllPassword for the database
PVAULT_DB_PORTint5432AllPort of the running database
PVAULT_DB_REQUIRE_TLSboolMode dependentAllVault tries to connect to the database with TLS. If this value is true and the connection fails, Vault does not start. If this value is false and the connection fails, Vault starts and connects without TLS
PVAULT_DB_MAX_OPEN_CONNSint16AllMaximum number of open connections to the backend database–do not modify unless requested to do so by the Piiano team
PVAULT_DB_MAX_IDLE_CONNSint16AllMaximum number of idle connections to the backend database–do not modify unless requested to do so by the Piiano team
PVAULT_DB_CONN_MAX_LIFETIME_MINUTESint5AllThe limit on the time, in minutes, a connection to the backend database is maintained–do not modify unless requested to do so by the Piiano team
PVAULT_DB_MAX_STRING_LENGTHint64AllThe maximum length of data types based on strings, including STRING, NAME, GENDER, CC_HOLDER_NAME, US_BANK_ACCOUNT_NUMBER, OBJECT_ID and TENANT_ID.
PVAULT_DB_MAX_BLOB_LENGTHint5242880AllThe maximum length of data types based on blobs.
PVAULT_DB_MAX_TOKEN_TAGSint10AllThe maximum amount of tags per token
PVAULT_DB_MIGRATION_AUTO_RUNbooltrueAllWhether Vault sets up the database during migration. Set to false when performing the database migration externally
PVAULT_DB_MIGRATION_ENABLE_RETRIESbooltrueAllWhether Vault performs retries for the database migration. When running the migration in Vault and multiple instances are running, this option must be true to handle race conditions. When running the migration externally, this can be set to false
PVAULT_DB_MIGRATION_INITIAL_WAIT_BETWEEN_RETRIESstring20msAllThe initial wait duration between retries for the migration exponential backoff
PVAULT_DB_MIGRATION_MAX_WAIT_BETWEEN_RETRIESstring5sAllThe maximum wait duration between retries for the migration exponential backoff
PVAULT_DB_MIGRATION_MAX_RETRIESint25AllThe maximum number of retries attempts for the migration exponential backoff
PVAULT_DB_GC_RETENTION_PERIODstring720hAllThe period for which archived objects and tokens are retained before becoming eligible for deletion by the prune job, delete objects and tokens REST API operation, and CLI delete objects and tokens command.

Stateless mode

PVAULT_BACKING_STOREstringpsqlServerThe backing store for Vault. By default it is 'psql' which tells Vault to store its state in the POSTGRES DB. The value 'none' tells Vault to run in stateless mode. In stateless mode Vault does not connect to a database. State is stored in memory. In stateless mode some methods are disabled.
PVAULT_GENERATE_SECRETSboolfalseServerThis variable is only applicable when PVAULT_BACKING_STORE is set to none. In this mode, Vault is a stateless server which stores all state in memory. When running Vault for the first time, this variable should be set to true. Vault will then write all keys needed for stateless operations, and the hashes of all user tokens into a file called pvault.secrets.json in the current directory. It will also print the user tokens to the console and then exit. Having done so once, you can then start Vault with this variable set to 0, false (or not set). Vault will then read and load the secrets from the file, allowing it to run in stateless mode.

Key management service

A key management service (KMS) should be configured. For more information on using a KMS and property encryption, see Key management service on the encryption page.

NameTypeDefault (Dev / Server)EditionDetails
PVAULT_KMS_URIstring""AllThe KMS key URI used for property encryption
PVAULT_KMS_SEEDstring""AllGenerate a local KMS using this seed (KMS_URI can be unset)

Service and features

NameTypeDefault (Dev / Server)EditionDetails
PVAULT_SERVICE_LISTEN_ADDRstring""AllListener address of Vault
PVAULT_SERVICE_ADMIN_API_KEYstring"pvaultauth"AllThe admin API key for authentication
PVAULT_SERVICE_FORCE_ACCESS_REASONbooltrueAllWhether Vault should force a valid access reason to be provided with calls
PVAULT_SERVICE_ADMIN_MAY_READ_DATAboolMode dependentAllWhether Admin is allowed to read data
PVAULT_FEATURES_ENCRYPTIONbooltrueAllThis variable is ignored in production. In production, properties set as is_encrypted are always stored encrypted. When this variable is set to false (only in PVAULT_DEVMODE), properties stored unencrypted.
PVAULT_FEATURES_POLICY_ENFORCEMENTbooltrueAllWhether policy management is enforced
PVAULT_FEATURES_MASK_LICENSEboolfalseAllWhether Vault's service license will be masked while retrieving it using Get license API or Get license CLI
PVAULT_SERVICE_TIMEOUT_SECONDSfloat30AllTimeout in seconds for REST API calls
PVAULT_SERVICE_DEFAULT_PAGE_SIZEint100AllThe default page size for object queries when the page size is not specified. The page size is the maximum number of objects that may be requested in one call.
PVAULT_SERVICE_MAX_PAGE_SIZEint1000AllThe maximum page size that can be specified for a call. The page size is the maximum number of objects that may be requested in one call.
PVAULT_SERVICE_CACHE_REFRESH_INTERVALstring30sAllThe refresh interval of the control data cache that serves the data APIs (under /api/pvlt/1.0/data/). If this value is zero the cache is disabled.
PVAULT_SERVICE_ARCHIVE_PRUNE_INTERVALstring0AllThe non-negative run interval for the prune job as a duration string. (See the definition of a duration string in the details for PVAULT_EXPIRATION_TOKENS.) Each time it runs, the pruning job deletes archived objects and tokens for which the retention period has elapsed. If the value is 0, the prune job is disabled.

Logs and telemetry

See Logs for more information on logs and telemetry.

NameTypeDefault (Dev / Server)EditionDetails
PVAULT_LOG_LEVELstring"info"AllLog level (supports debug, info, warn, and error)
PVAULT_LOG_DATADOG_ENABLEstring"logs,stats,config"AllEnable Datadog logs and metrics. comma seperated list of sources (logs,audit,stats,config,none).
PVAULT_SENTRY_ENABLEbooltrueAllEnable Sentry telemetry logging
PVAULT_LOG_CUSTOMER_IDENTIFIERstring AllIdentifies the customer in all the observability platforms
PVAULT_LOG_CUSTOMER_ENVstring AllIdentifies the environment in all the observability platforms. Recommended values are PRODUCTION, STAGING, and DEV
PVAULT_LOG_AUDIT_ENABLEbooltrueAllEnable audit logging to stdout


See TLS for more information on configuring Piiano Vault to use TLS.

NameTypeDefault (Dev / Server)EditionDetails
PVAULT_TLS_SELFSIGNEDboolfalseAllWhether Vault runs with a self-signed TLS key (valid for 24h)
PVAULT_TLS_ENABLEboolMode dependentAllWhether Vault listens on HTTPS (TLS). If false, Vault listens on HTTP. If PVAULT_TLS_SELFSIGNED is true, this setting is ignored and Vault listens on HTTPS.
PVAULT_TLS_CERT_FILEstring""AllPath to the TLS certificate file. Must be valid to enable listening on HTTPS (TLS)
PVAULT_TLS_KEY_FILEstring""AllPath to the TLS key file. Must be valid to enable listening on HTTPS (TLS)


NameTypeDefault (Dev / Server)EditionDetails
Objects don't expire
AllDefault expiration time for tokens as a duration string. A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
Objects don't expire
AllDefault expiration time for associated objects as a duration string. (See the definition of a duration string in the details for PVAULT_EXPIRATION_TOKENS.)
Objects don't expire
AllDefault expiration time for unassociated objects as a duration string. (See the definition of a duration string in the details for PVAULT_EXPIRATION_TOKENS.)

The duration string is a decimal fraction with a time unit suffix, such as "300ms", "-1.5h", or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", and "h".

Docker Compose configurations

These environment variables can be used when installing Piiano Vault server using Docker Compose:

SERVER_API_PORTint8123Server / ServerXListener port for Vault Server and of the router (Traefik) for ServerX
CONTROL_API_PORTint8123ServerXListener port for the control plane of Vault
DATA_API_PORTint8123ServerXListener port for the data plane of Vault
TRAEFIK_DASH_PORTint8080ServerXListener port for the router (Traefik) dashboard