Environment Variables

Environment Variables can be used to configure the dashboard - these are especially useful for automated deployments.

Server / Dashboard

These should be used to configure the dashboard application and are set against the dashboard or “server” container in containerised deployments.

Dashboard settings

Variable

Description

Version Introduced

Variable

Description

Version Introduced

PI_AUTH_SSO

Enable Single Sign On for the dashboard using Windows Authentication

 

PI_LICENCE

Inline licence file content (XML or UUID)

 

PI_LICENCE_URL

Link to the dashboard licence

 

PI_LICENCE_FILE

Disk location of a licence file

 

RENDERER_DASHBOARD_URL

URL for the dashboard used when rendering. Default: http://localhost:8224/pi

 

PI_SYSTEM_ADMIN_TOKEN

A token created by you, min 15 chars, used as a bearer auth token in a post request to the /health endpoint to view dashboard metrics including licence & memory info

 

PI_EMAIL_SMTP_SERVER

The smtp server any mail will be sent via

June 24

PI_EMAIL_PORT

The smtp port

June 24

PI_EMAIL_USERNAME

The smtp username

June 24

PI_EMAIL_ADDRESS

The smtp email address (optional)

June 24

PI_EMAIL_PASSWORD

The smtp password

June 24

PI_EMAIL_SSL

Sets smtp with ssl (boolean)

June 24

PI_EMAIL_TLS

Sets smtp with tls (boolean)

June 24

PI_EMAIL_ALLOW_UNVERIFIED_CERTS

Allow unverified tls certificates (not recommended)

June 24

PI_VARIABLE_PAN_RENDERER_URL

Sets the dashboard variable PAN_RENDERER_URL

June 24

PI_VARIABLE_PAN_SCHEDULER_URL

Sets the dashboard variable PAN_SCHEDULER_URL

June 24

PI_VARIABLE_PAN_EXCEL_READER_URL

Sets the dashboard variable PAN_EXCEL_READER_URL

June 24

PI_VARIABLE_ANALYTICS_SERVER_URL

Sets the dashboard variable ANALYTICS_SERVER_URL

June 24

Repository Database configration

Variable

Description

Version Introduced

Variable

Description

Version Introduced

PI_DB_HOST

Database host

 

PI_DB_PORT

Database port

 

PI_DB_USERNAME

Database username

 

PI_DB_PASSWORD

Database password

 

PI_DB_MAX_MEMORY

Maximum RAM allocated to the database

 

PI_DB_SCHEMA_NAME

Schema name of the database (Default: dashboard)

 

PI_EXTERNAL_DB

Set to true if the database is remote or false if otherwise

 

PI_DB_USER_ACCOUNT_NAME

The name of the user account under which Database should run

 

PI_DB_USER_ACCOUNT_PASSWORD

Password for user account set by PI_DB_USER_ACCOUNT_NAME variable

 

PI_DB_USE_SSL

Set to true if the database is configured to use ssl or false if otherwise

 

PI_DB_IS_MYSQL

Set to true if the database is MySQL 8

PI_DB_SKIP_MIGRATIONS

Set to true if you want to stop migrations from running upon startup

April 2024

Tomcat settings

Variable

Description

Version Introduced

Variable

Description

Version Introduced

PI_TOMCAT_PORT

Dashboard port

 

PI_TOMCAT_INTERNAL_PORT

Tomcat internal port (local only) (see PI_TOMCAT_USE_HTTPS)

default 28748

 

PI_TOMCAT_ADMIN_PORT

Tomcat's administration port

 

PI_TOMCAT_AJP_PORT

Tomcat AJP port

 

PI_TOMCAT_MAX_MEMORY

Maximum memory allocated to tomcat

 

PI_TOMCAT_MAX_CONNECTIONS

Maximum concurrent connections to the tomcat server

 

PI_TOMCAT_CONNECTION_TIMEOUT

Connection timeout definition

 

PI_TOMCAT_MAX_THREADS

Maximum threads tomcat can run

 

PI_TOMCAT_MIN_SPARE_THREADS

Minimum spare threads tomcat should keep

 

PI_TOMCAT_FRAME_ANCESTORS

Frame-Ancestors definition for dashboard embedding. A space separated list of scheme://host:port or one of 'none' or 'self'

 

PI_TOMCAT_X_FRAME_OPTIONS

X-Frame-Options setting for Dashboard (this is only for Internet Explorer. Chrome, Edge, Mozilla, and other modern browsers would use Frame-Ancestors).

 

PI_TOMCAT_USE_HTTPS

Makes tomcat use HTTPS

April 2021

PI_TOMCAT_HTTPS_CERT

The location of the X509 certificate to use for https

April 2021

PI_TOMCAT_HTTPS_CERT_KEY

The location of the X509 certificate key file

April 2021

PI_TOMCAT_HTTPS_CERT_KEY_PASSWORD

The password of the certificate key (if set)

April 2021

PI_TOMCAT_COOKIE_SECURE

Must be true if the dashboard is somehow being served with HTTPS. Default: false. If your https is provided by an external application/layer you should also set PI_PROXY_IS_SECURE totrue .

November 2020

PI_TOMCAT_COOKIE_SAMESITE

One of nonelax or strict. Default: strict

November 2020

PI_TOMCAT_COOKIE_NAME

The cookie name that is used to identify a user’s session to a particular dashboard. Defaults to DASHBOARDSESSIONID<port> (e.g. a dashboard running on port 8224 will have its cookie as DASHBOARDSESSIONID8224.

August 2021

PI_TOMCAT_MAX_TOTAL_DB_CONNECTIONS

Maximum number of connections to the dashboard’s own database. Default: 150 - updated from 15 to 150 in the February 23 release

March 2022

PI_TOMCAT_ENABLE_SESSION_SYNC

Used to enable session sync

March 2022

PI_TOMCAT_SESSION_SYNC_MODE

Choose either Tomcat session sync (tcp) or Redis session offload (redis)

October 2023

PI_TOMCAT_SESSION_SYNC_BROADCAST_PORT

Used to set the session sync broadcast port

March 2022

PI_TOMCAT_SESSION_SYNC_LISTENING_PORT

Used to set the session sync listening port

March 2022

PI_TOMCAT_SESSION_SYNC_REDIS_HOST

Set the redis host if session sync mode is redis

October 2023

PI_TOMCAT_SESSION_SYNC_REDIS_PORT

Set the redis port if session sync mode is redis

October 2023

PI_TOMCAT_SESSION_SYNC_REDIS_PASSWORD

Set the redis password if session sync mode is redis

October 2023

PI_TOMCAT_USE_HSTS

Boolean field. Apply HSTS to the dashboard.

July 2022

PI_TOMCAT_HSTS_INCLUDE_SUBDOMAINS

Boolean field. Applies HSTS to all subdomains of your site.

July 2022

PI_TOMCAT_HSTS_PRELOAD

Boolean field. Enables HSTS preload header, meaning browsers will never connect to your domain using an insecure connection.

You should only enable preload if you are confident your entire site and all of its subdomains can be served over HTTPS. Once on the HSTS preload list, it can take several months to remove your site if needed.

July 2022

PI_TOMCAT_HSTS_MAX_AGE

The amount of time in seconds that the browser should remember that the site is only to be accessed using HTTPS. Default setting of 31536000.

July 2022

PI_TOMCAT_USER_ACCOUNT_NAME

The name of the user account under which Tomcat should run

January 2023

PI_TOMCAT_USER_ACCOUNT_PASSWORD

Password for user account set by PI_DB_USER_ACCOUNT_NAME variable

January 2023

PI_TOMCAT_LOGGING_MAX_AGE

The amount of time (in days) to retain rotated log files.

Default setting of 0. A value of 0 disables automated log removal

October 2023

PI_TOMCAT_LOGGING_LOG_LEVEL

The minimum log level for Tomcat and Dashboard logs. Default setting of INFO. (Options: DEBUG, INFO, WARN, ERROR)

November 2023

PI_TOMCAT_LOGGING_JSON

Log in json format. Defaults to false.

May 2024

PI_TOMCAT_LOGGING_ACCESS_LOG

Log http requests. Defaults to true.

May 2024

PI_TOMCAT_COOKIE_PARTITIONED

Set to true by default, determine whether cookies will be partitioned, currently incompatible with open id pop up login via an iFrame

February 2024

PI_TOMCAT_HTTPS_CERT_CHAIN

 

The location of the HTTPS certificate chain file

June 2024

PI_TOMCAT_CIPHERS

A list of ciphers as a single string, with each cipher separated by a comma (e.g. “TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256")

Defaults to a ciphers list supported by the dashboard.

June 2024

 

Proxy

These settings are only required if you want tomcat to do any URL rewriting. This is generally a good idea if you're using IIS as a reverse proxy. Nginx and Apache httpd are more than capable of doing this on their own though.

Variable

Description

Version Introduced

Variable

Description

Version Introduced

PI_PROXY_ENABLED

Let tomcat know it's behind a proxy (this will make it know how to rewrite its URLs)

 

PI_PROXY_SCHEME

One of http or https

 

PI_PROXY_IS_SECURE

If the proxy is using https protocol (generally true)

 

PI_PROXY_HOST

Proxy host (usually the publicly accessible domain)

 

PI_PROXY_PORT

Proxy port

 

 

Renderer

These should be used to configure the renderer application and are set against the renderer container in containerised deployments

Renderer settings

Variable

Description

Version Introduced

Variable

Description

Version Introduced

RENDERER_PORT

Internal port to run on. Default 9915

 

RENDERER_POST_LIMIT

Size limit that the server accepts when POSTed to. Default: 5mb

 

RENDERER_LOGGER_TYPE

Type of logger. Default tomcat

 

RENDERER_LOG_PATH

Path to the directory containing the logs. Default ../../tomcat/logs

 

RENDERER_LOG_LEVELS

Comma separated string with the levels to log. Valid values: error,info,warn,debug,verbose. Default error,warn,info,debug

 

RENDERER_IGNORE_HTTPS_ERRORS

Boolean field. If set to true, the Renderer will ignore errors related to the use of self-signed or invalid SSL certificates. Default false

November 2022

DIE_ON_UNHEALTHY

Boolean field. Kill the container if it reports as unhealthy. This is for orchestrators that only monitor running/stopped states. Default false

March 2021

RENDERER_USER_ACCOUNT_NAME

The name of the user account under which Renderer service should run

January 2023

RENDERER_USER_ACCOUNT_PASSWORD

Password for user account set by PI_DB_USER_ACCOUNT_NAME variable

January 2023

RENDERER_TIMEOUT_IN_SECONDS

Timeout value in seconds to determine how long it should wait for the URL to load in the chromium browser before the renderer task terminates - default value is 900 seconds (15 minutes)

May 2024

RENDERER_LOGGER_JSON

Log in JSON format. Defaults to false

May 2024

Excel Reader

These should be used to configure the Excel reader application and are set against the excel-reader container in containerised deployments

Excel Reader Settings

Variable

Description

Version Introduced

Variable

Description

Version Introduced

EXREAD_BIND_ADDRESS

Host to bind to. Default 0.0.0.0

 

EXREAD_PORT

Internal port to run on. Default 9916

 

EXREAD_ACCESS_CONTROL_ALLOW_ORIGIN

Access control allow origin value. Default *

 

EXREAD_LOG_PATH

Path to the directory that holds the logfile. Default logs/

 

EXREAD_LOG_LEVEL

Log level (DEBUG,INFO,WARN,ERROR). Default WARN

 

EXREAD_USER_ACCOUNT_NAME

The name of the user account under which Excel-Reader service should run.

January 2023

EXREAD_USER_ACCOUNT_PASSWORD

Password for user account set by PI_DB_USER_ACCOUNT_NAME variable

January 2023

Scheduler

These should be used to configure the scheduler application and are set against the scheduler container in containerised deployments

Scheduler Settings

Variable

Description

Version Introduced

Variable

Description

Version Introduced

SCHEDULER_LOGGING_DIR

Path to the directory that keeps the logs. Default: ./logs]

 

SCHEDULER_LOGGING_LEVEL

Minimum log level. Default: ERROR].

 

SCHEDULER_PORT

Port that the scheduler is listening on. Default: 9917]

 

SCHEDULER_JWT_KEY_PATH

Location where the key pairs are kept. Default: ../keys]

 

SCHEDULER_DASHBOARD_URL

URL to the dashboard. Default: http://localhost:8224/pi]

 

SCHEDULER_USER_ACCOUNT_NAME

The name of the user account under which Scheduler service should run

January 2023

SCHEDULER_USER_ACCOUNT_PASSWORD

Password for user account set by PI_DB_USER_ACCOUNT_NAME variable

January 2023

Pirana

These should be used to configure the Pirana application and are set against the Pirana container in containerised deployments

Pirana Settings

Variable

Description

Version Introduced

Variable

Description

Version Introduced

PIRANA_BIND_ADDRESS

Host to bind to. Default 0.0.0.0

 

PIRANA_PORT

Internal port to run on. Default 9918

 

PIRANA_POOL

Connection pool. Default 30

 

PIRANA_ENV_TYPE

Environment type to run on. Default production

 

PIRANA_LOGFILE

Path to the logfile. When left empty logs to stdout

 

PIRANA_LOG_LEVEL

Minimum log level. Default: INFO

October 2024 

PIRANA_SSL_ENABLED

Enable options below. Default false

 

PIRANA_SSL_CERTIFICATE

Path to an SSL certificate

 

PIRANA_SSL_PRIVATE_KEY

Path to an SSL private key

 

PIRANA_SSL_CERT_CHAIN

Path to an SSL certificate chain

 

PIRANA_MODEL_SEED

Seed number for the model. Default 123456789

 

PIRANA_MODEL_MAX_DEPTH

Maximum model depth. Default 4

 

PIRANA_MODEL_FILL_STRATEGY

Fill strategy for missing data. Default fill

 

PIRANA_USER_ACCOUNT_NAME

The name of the user account under which Pirana service should run

January 2023

PIRANA_USER_ACCOUNT_PASSWORD

Password for user account set by PI_DB_USER_ACCOUNT_NAME variable

January 2023

PIRANA_LOGGER_JSON

True to output logs in JSON format. Default: false

October 2024